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PREFACE 











PURPOSE 





This manual provides documentation for application programmers 
who want to write high-level language programs that define and 
manipulate the data in an ORACLE RDBMS. 


ORACLE provides two programmatic interfaces for application 
programmers. The first, and perhaps the most efficient for develop- 
ing an application, is the precompiler interface. By using the pre- 
compiler interface, it is possible to write an application in a high-level 
language (such as FORTRAN, Pascal, C, PL/I, or Cobol) that 
contains embedded statements written in the SQL language. The 
precompiler translates the SQL statements embedded in this program 
into high-level source code that can then be compiled and linked 
with the appropriate run-time libraries to form executable code. 


Using the Pro*C precompiler enables application programmers to 
combine the most appropriate features of both C and SQL in a single 
application. 


The second interface, called the ORACLE Call Interface, (previously 
known as the High Level Interface, or HLI) also allows high-level 
language applications to access data in an ORACLE Relational Da- 
tabase Management System. Programs that use the ORACLE Call 
Interface can make direct calls to ORACLE subroutines contained 
in the language-specific run-time libraries. 


Both of these interfaces enhance the process of developing an appli- 
cation program that will be used to define and manipulate data in 
an ORACLE database. 
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AUDIENCE 








This manual is designed for application programmers who are using 
one of the high-level interfaces provided by ORACLE. Readers of 
this manual should be familiar with these areas: 

èe programming in C 

e accessing data in an ORACLE RDBMS 


e the SQL language 


ORGANIZATION OF THIS MANUAL 
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This manual is divided into two parts: Part I contains information 
on using the C Precompiler Interface, and Part II documents the 
ORACLE Call Interface(OCN. 


An outline of the manual follows: 


1. An Introduction to Pro*C This chapter is a general introduction 
to Pro*C. It discusses why you would use it, general 
concepts and definitions, parts of a Pro*C program, 
types of statements found in a Pro*C program, and an 
example of the PCC command. 


2, Elements of a Pro*C Program This chapter discusses declaring 
the variables to be used in a Pro*C program. It discusses 
the required items in the Application Prologue, and it 
contains several short code examples, from logging in and 
out of ORACLE, to very short programs which create 
tables or insert records. 


3. Queries This chapter introduces the concept of cursors, which are 
used to return the results of most queries. After the 
various cursor commands are introduced, two example 
programs are included. 


4. Committing and Rolling Back Work This chapter defines a 
transaction or logical unit of work, which may group se- 
veral SQL statements together as one unit. The pro- 
grammer can write a program such that be can control 
when the transactions done by the program are commit- 














ted (made “permanent” in the database) or rolled back 
(‘erased” from the database). 


Error Detection and Recovery In this chapter the programmer 


learns how to use the SQLCA and indicator variables, to 
detect and act on different conditions, such as null values, 
non-conditional deletes, no row returned, and data over- 
flow or truncation. 


. Dynamically Defined Statements This chapter covers advanced 


programming techniques, which are useful for writing 
extremely flexible programs, but require greater under- 
standing of the programmer about coding in C and the 
SQL language. Beginning Pro*C users should either skip 
or skim this chapter. 


. Invoking Pro*C (The PCC Command) The PCC command and 


its options are described in this chapter. 


. Introduction to Pro*SQL This chapter introduces concepts used 


in writing a Pro*SQL program, such as cursor data area, 
logon data area, return codes, types of parameters, and 
program structure. 


. Individual Program Call Descriptions This chapter introduces 


each OCI call. A section on each call shows the general 
syntax, and gives an example in C. Calls are discussed 
in the general order they might appear, rather than al- 
phabetically. (Note that a call summary showing calls in 
alphabetical order can be found in an appendix.) 


10. Old Pro*SQL(OCD Calls This chapter summarizes older calls, 


replaced by those in Chapter 2, but which have been in- 
cluded here for completeness. A section for cach call 
shows the general syntax, includes a discussion of its use 
and parameters, and gives an example in C. Calls are 
discussed in the general order they might appear in a 
program, rather than alphabetical order. (Note that an 
appendix summarizes these calls in alphabetical order.) 


11. Datatypes This chapter discusses the datatypes used by the OCI 


and the ORACLE RDBMS, as well as the conversions 
that can be performed. 


Appendix A: Pro*C Error Messages This appendix lists Pro*C er- 


ror messages. 
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Appendix B: C Programming Guidelines This appendix gives some 
general hints for writing Pro*C programs. 


Appendix C: Reserved Words This appendix lists the words reserved 
for use by ORACLE RDBMS or Pro*C, which cannot 
be used for user-named ORACLE objects, such as ta- 
bles, columns, or views. 


Appendix D: Sample Pro*C Program This appendix contains a 
listing of a sample program which is included on the 
object code media distributed to Pro*C users. 


Appendix E: Sample Pro*C Program with Dynamic SQL This ap- 
pendix contains a listing of a sample program, using dy- 
namic SQL, which is included on the object code media 
distributed to Pro*C users. 


Appendix F: Example C Program Using the ORACLE Call Inter- 
face This appendix contains a complete C program 
which prompts users for input (information about em- 
ployees) and adds new employee records to the database 
after performing some checking. 


Appendix G. Program Call Summary This appendix contains an 
alphabetical summary of all OCI calls in this manual, 
and is useful as a quick reference. 


RELATED PUBLICATIONS 
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Along with this manual you may want to refer to the following 
publications by ORACLE Coproration. You will automatically re- 
ceive titles which relate to products you have purchased; you will not 
necessarily need nor receive all documents. The release notes are 
udpated frequently to reflect recent changes in the products. 


Oracle Corporation publications: 
Documentation parts for the ORACLE RDBMS are: 


© ORACLE RDBMS Release Notes ORACLE Part No. 3001 


® ORACLE Overview and Introduction to SQL ORACLE Part 
No. 3801 














e 


The ORACLE Database Administrators Guide ORACLE Part 
No. 3601 


ORACLE Utilities User's Guide ORACLE Part No. 3602 


ORACLE Report User's Guide: RPF/RPT ORACLE Part No. 
3603 


ORACLE Error Messages and Codes ORACLE Part No. 3605 


Documentation parts for the various precompiler products (Pro*C, 
ProtFORTRAN, Pro*COBOL, Pro*PL/I) are: 


o 


° 


Pro*ORACLE Release Notes ORACLE Part. No: 3007 
Pro*C User's Guide ORACLE Part No. 3504 
Pro*COBOL User's Guide ORACLE Part No. 3503 
Pro* FORTRAN User's Guide ORACLE Part No. 3502 
Pro*PL|I User's Guide ORACLE Part No. 3505 
Pro*Pascal User's Guide ORACLE Part No. 3506 
Pro*Ada User's Guide ORACLEPart No. 3507 


Documentation parts for the product SQL*Plus are: 


o 


e 


SQL*Plus Release Notes ORACLE Part No, 3003 
SQL* Plus User's Guide ORACLE Part No. 3201 

A Quick Tour of SQL* Plus ORACLE Part No. 3803 
SOL*Plus Quick Reference ORACLE Part No. 3703 


Documentation parts for the SQL*Forms product are: 


SQL*Forms Release Notes ORACLE Part No. 3004 
SQL*Forms Operator's Guide ORACLE Part No. 3301 
SQL*Forms Designer's Tutorial ORACLE Part No. 3302 
SQL* Forms Designer's Reference ORACLE Part No. 3304 
SQL*Forms User's Quick Reference ORACLE Part No. 3704 


SQL* Forms Designer's Quick Reference ORACLE Part No. 
3708 


A Quick Tour of SQL* Forms ORACLE Part No. 3804 
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Documentation parts for the SQL*Menu product are: 

© SQL*Menu Release Notes ORACLE Part No. 3009 

°  SQL*Menu User's Guide ORACLE Part No. 3303 
Documentation parts for the Hasy*SQL product are: 

e  Easy*SQL Release Notes ORACLE Part No. 3002 

è Introduction to Easy*SQL ORACLE Part No. 3810 

e  Easy*SQL User's Guide ORACLE Part No. 3101 

° A Quick Tour of Easy*SQL ORACLE Part No. 3802 
°  Easy*SQL Reference Card ORACLE Part No. 3702 
Documentation parts for the SQL*Graph product are: 

© SQL*Graph Release Notes ORACLE Part No. 3006 

°  SQL*Graph User's Guide ORACLE Part No. 3402 

°% A Quick Tour of SOL*Graph ORACLE Part No. 3806 
° = SQL*Graph Quick Reference ORACLE Part No. 3706 
Documentation parts for the SQL*Cale product are: 


è? — Introduction to SQL*Cale for Lotus 1-2-3 Users ORACLE Part 
No. 3809 


° SQL*Cale Release Notes ORACLE Part No. 3005 

© SQL*Cale User's Guide ORACLE Part No. 3401 

© A Quick Tour of SQL* Cale ORACLE Part No. 3805 
© SQL*Cale Quick Reference ORACLE Part No. 3705 


For every operating system on which ORACLE is supported, an 
installation and user’s guide is also provided, as in: 


¢ ORACLE for DEC VAX/VMS Installation and User's Guide 
ORACLE Part No. 1001 


è ORACLE for IBM VMISP Installation and User's Guide 
ORACLE Part No. 1003 











CONVENTIONS USED IN THIS MANUAL 





The following conventions are observed in the documentation for the 
ORACLE RDBMS and related products: 


Filenames Filenames appear in capital letters, as in INIT.ORA. 
Portions of the filenames which may vary appear in 
lower case, as in SGADEFx.ORA. 


Reserved words and keywords These words also appear in capital 
letters in examples and in text, to indicate that they are 
to be entered as is, and that they have reserved meanings 
within ORACLE. 


Key names Key names appear in capital letters, and are enclosed in 
square brackets as in [RETURN]. 


Command Syntax 





Commands This font is used to identify text which must be entered 
exactly as shown: 


SELECT * FROM 


Variables Variables appear in italics. Users must substitute an ap- 
propriate value. 


Alternative items Alternative choices are always separated by vertical 
bars. ‘The set of alternative choices is enclosed by curly 
braces if one of the items is required, or by square 
brackets if the item is an optional alternative. (See below 
for the notation convention for required or optional 
items.) 


Required items Required items are enclosed in curly braces. Users 
must choose one of the alternatives. 


Optional items Optional items are enclosed in square brackets. 


Note that square brackets may also enclose parts of 
words as in: 
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ro 
Cry 





sfelect] ... 


Repetitive items An ellipsis represents an arbitrary number of similar 
items. 


New or revised material Newly added or revised material is high- 
lighted with a bar in the margin, as demonstrated by this 
paragraph. 


The following symbols should always be entered as they appear in 
the command format: 


period 
comma 
hyphen 
semicolon 
colon 
equal sign 
asterisk 
parentheses 


YOUR COMMENTS ARE WELCOME 





xii / Pro*C User’s Guide 


Oracle values and appreciates your comments as an ORACLE user 
and reader of the manuals. As we write, revise, and evaluate, your 
opinions are the most important input we receive. At the back of 
this manual is a Reader’s Comment Form which we encourage you 
to use to tell us both what you like and dislike about this (or other) 
ORACLE manuals. If the form is gone, or you would like to con- 
tact us, please use the following address, or call us at (415) 598-8000. 


Technical Publications Manager 
Oracle Corporation 

20 Davis Drive 

Belmont, California 94002 
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PART I: PRO*C PRECOMPILER INTERFACE 














The chapters that follow provide a complete description of the Pro*C pre- 
compiler interface, Part I describes the overall structure of a Pro*C pro- 
gram, and presents the syntax for Pro*C statements. Other topics covered 
include error handling, transaction control, cursors, precompiler usage and 
command options, and programming guidelines. Numerous examples are 


included to illustrate each concept as it is presented. 
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CHAPTER 1. AN INTRODUCTION TO PRO*C 


ee a 





This chapter is a general introduction to Pro*C. It discusses why you 
would use it, general concepts and definitions, parts of a Pro*C program, 
and types of statements found in a Pro*C program. 


The SQL data language is a non-procedural language. That is, most state- 
ments are executed independently of preceding or following statements. 
Compare this to programming languages, such as C, Fortran, COBOL, or 
PL/L Those languages, called procedural, are based on constructs such as 
loops”, “branches”, and “if/then” pairs. Whereas the SQL language isa 
very powerful one, nevertheless it has some limitations without procedural 
capabilities. 


Having specifically designed SQL to be a non-procedural language, and 
thus, understanding the limitations of such a language, the originators of 
SQL also explicitly designed SQL constructs to be embedded in procedural 
programming languages, such as C. With these constructs, programmers 
can design applications which combine the best features of SQL and the 
best features of the programming language (the host language), ‘These ap- 
plications are more powerful and flexible than applications based on either 
C or SQL alone. 


The ORACLE Relational Database Management System includes several 
tools to allow programmers to write programs in a host language to access 
data in an ORACLE database. Currently, tools are provided for the lan- 
guages C, FORTRAN, COBOL, Pascal and PL/I. 


WHAT IS PRO*C ? 





The Pro*C tool provided with the ORACLE RDBMS is designed to con- 
vert a C program which includes SQL statements into a C program which 
can access and manipulate data in an ORACLE database. As a pre- 

compiler, Pro*C converts the EXEC SQL statements found in its input file 
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to appropriate ORACLE calls in an output file. That output file can sub- 
sequently be compiled, linked, and executed in the normal manner for C 
programs. 


Compare Pro*C (or similar products, such as Pro*Fortran and Pro*PL/I) 
to the ORACLE Call Interface (previously called Pro *SQL). ORACLE 
Call Interface(OCI) is the call interface to an ORACLE database, which 
allows users to embed ORACLE calls directly in high-level languages such 
as C, FORTRAN, or COBOL. Every transaction is accomplished through 
multiple calls and the use of a cursor. 


FEATURES AND BENEFITS OF PRO*C 
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Some of the features of the Pro*C compiler are: 


®  Pro*C calls are more conceptual, and therefore easier to understand, 
than Pro*SQL(OCD) calls. 


° One Pro*C(OCY) call is automatically translated to the equivalent of 
several run-time library calls, reducing programming time. 


e One program can be used against data in different databases. 


e Multiple programs can be separately precompiled and executed to- 
gether. 


GENERAL CONCEPTS 


Using the Pro*C tool adds another step into the programmer’s normal 
programming process; however, this additional step causes the Pro*C tool 
to do a fair amount of work on behalf of the programmer. The normal 
sequence of events in writing and running a C program is shown in 
Figure 1 on page 5. 





rn 





n 





1. Write a C program. 
2. Compile the program, resulting in an output object file. 


3. Link-edit the object file, resulting in an executable file. 
4. Run the program to perform the desired work. 





Figure 1. Steps in Writing a C Program 


luded Pro*C statements in the original program 


If the programmer has ine 
Id include an additional one at the beginning, as 


(PROG.C), the steps wou 
shown in Figure 2. 





i. Write a Pro*C program. 

2. Precompile the program using Pro*C, 
resulting in the output file. 

3. Compile the program, resultin 
4, Link-edit the object file, 
resulting in an executable file. 

5, Run the program to perform the desired work. 


g in the object file. 





Figure 2, Steps in Writing a Pro*C Program 


The Pro*C Command 





g the Pro*C precompiler are described 
PCC Command)’. You will also find 
several files to run together, 


The syntax and options for runnin, 
in detail in “Invoking Pro*C (The 
information in that chapter on precompiling 
and using Pro*C and the OCI together. 


Mixing C Commands and SQL Statements 


Any valid SQL statement may be executed from a C program. While there 
are some required “parts” or statements in a Pro*C program and a basic 
“order” of appearance, note that C programming lines may appear at any 
point in the program (following C programming standards, of course). The 
required parts are introduced in “Parts of the Pro*C Program” and de- 
scribed in more detail in subsequent sections. 
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The Command Prefix EXEC SQL 





To minimize the language difficulties that might be caused by interspersing 
SQL statements into many different host languages, all SQL statements are 
prefixed with the words EXEC SQL. One purpose of the precompiler, 
then, is to translate all statements beginning with EXEC SQL into the ap- 
propriate source language code for database calls (assumed to be C in this 
manual). 


The Command Prefix EXEC ORACLE 





While most Pro*C statements are prefixed by the words EXEC SQL, some 
statements are prefixed by EXEC ORACLE. While any number of SQL 
statements require the EXEC SQL prefix, there is a fixed, smaller set of 
commands requiring EXEC ORACLE; see “The EXEC ORACLE 
Options” for a description and list of those statements. These statements 
are not compatible with SQL, and are unique to ORACLE precompilers. 


Executable and Declarative SQL Statements 
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SQL statements which may be included in a ProtC program fall into one 
of two groups: executable or declarative. All statements, whether execut- 
able or declarative, are prefixed with the words BXEC SQL. 


Executable SQL statements are SQL statements which gencrate actual calls 
to the database. They include, but are not limited to, Data Manipulation 
statements (DML), Data Definition statements (DDL), and Data Control 
statements (DCL). After an executable SQL statement has been executed, 
the SQLCA (SQL Communications Area) contains a set of return codes. 


A logical unit of work is begun with the execution of the first executable 
SQL statement, except for CONNECT. Therefore the first executable SQL 
statement encountered after a CONNECT, COMMIT, or ROLLBACK 
WORK statement will begin a new logical unit of work. 


Declarative SQL statements generate no code and have no effect on logical 
units of work. The SQLCA is not affected by declarative statements. The 
declarative SQL statements are shown in Figure 3 on page 7. 











WSQL Declarative Statements 
BEGIN DECLARE SECTION 
END DECLARE SECTION 
WHENEVER ... 

DECLARE CURSOR ... 
INCLUDE ... 








Figure 3. The SQL Declarative Statements 


Parts of the Pro*C Program 


A Pro*C program contains two parts, both of which are required by the 
Pro*C processor: 


o ‘The Application Prologue (described in “The Application Prologue’). 
o ‘The Application Body (described in “The Application Body”). 


The Application Prologue defines variables and does general preparation for 
the Pro*C program. The Application Body basically contains the Pro*C 
calls, including SQI statements such as INSERT or UPDATE, to manip- 
ulate the ORACLE data. C code may surround any of the sections of code 
required by the Pro*C processor. 

The next chapter, “Elements of a Pro*C Program’ describes the Applica- 
tion Prologue, and contains some short sample Pro*C programs, to illus- 
trate the basic principles of a Pro*C program. 
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CHAPTER 2. ELEMENTS OF A PRO*C PROGRAM 








This chapter identifies the requisite elements of a Pro*C program, by de- 

fining several Pro*C terms and giving examples. At the end of the chapter 
ate several short sample programs, which will give you an idea of the min- 
imum requirements for a Pro*C program, as well as something to build on 


when writing your first program. 

In this chapter the C program refers to the module being precompiled, even 
if the module defines multiple functions or is only one of several modules 
for the application. 


THE APPLICATION PROLOGUE 


Near the beginning of every Pro*C program is the Application Prologue, 
which always contains three parts: 


1. The DECLARE Section, to name host variables. 


2. The INCLUDE SQLCA statement, to name the SQL Communi- 
cations area, which provides for error handling. (This replaces the C 
#include convention, for cross language compatibility.) 


3. The CONNECT statement, to connect to the ORACLE RDBMS. 


Only C programming statements may precede these statements in a Pro*C 
program. 


The Prologue: The DECLARE Section 





In the DECLARE Section all the host variables which will be used in the 
C program are named (“declared”). The DECLARE Section begins with 


the statement: 
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Host Variables 


EXEC SQL BEGIN DECLARE SECTION; 


and ends with the statement: 


EXEC SQL END DECLARE SECTION; 


Between these two statements the only type of statement allowed is one 
which declares either host variables or indicator variables. 


Only one BEGIN/END DECLARE section is allowed per precompiled 
unit, but a program may contain several independently precompiled units. 
The Section Declare may occur in the global or local declaration section, 


If a host or indicator variable is referenced in an EXEC SQL statement in 
a C program, but the variable has not been declared in the DECLARE 
section, the following message appears when the program is precompiled: 


Undeclared host variable a at line b in file c 


where a is the variable’s name, 6 is the line number where it was used, and 
c is the name of the file using the variable. 


Host variables must be declared for every value which will be referenced in 
both SQL statements and programming statements. Their datatypes must 
be declared using the host language in the DECLARE section. Their 
datatypes need not match the ORACLE datatype used when the table was 
defined; ORACLE will perform all reasonable conversions between the 
host language datatypes and ORACLE datatypes. 


EXEC SQL BEGIN DECLARE SECTION 
int pempno; /* employee number */ 


char pname[11];  /* employee name */ 
int pdeptno; /* department number */ 
EXEC SQL END DECLARE SECTION 








Figure 4. Sample DECLARE Section 
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Guidelines for Host Variables 


Indicator Variables 





The declaration found in Figure 4 on page 10 declares three host variables 
(PEMPNO, PNAME, PDEPTNO) which appear in the following SQL 
statement which might appear later in the program (in the application 
body): 


EXEC SQL SELECT DEPTNO, ENAME 
INTO :PDEPTNO, :PNAME 
FROM EMP 
WHERE EMPNO = :PEMPNO, 


A host variable: 

e must be explicitly declared in the DECLARE section 

© must be used in the same upper/lower case format as it was declared 
o must be preceded by a colon (:) in the SQL statement 

e must not be preceded by a colon in C statements 

o must not be a SQL reserved word (see Appendix C) 

e can only be used where a constant can be used 

o may have an associated indicator variable. 


(Indicator variables are described in the next section.) Note that in Version 
5 Pro*C does not null terminate strings. 


Indicator variables are optional variables which correspond, one to one, 
with host variables declared in the DECLARE section. They are primarily 
useful for dealing with NULL values. They are used to store individual 
field return codes which indicate either “null value returned” or “character 
field truncated”. 


Indicator variables can also be used to insert NULL values. (See “Using 
Returned Values in Indicator Variables”.) 


Guidelines for Indicator Variables 


An indicator variable: 
è must be explicitly declared in the DECLARE section 


e must be used in the same upper/lower case format as it was declared 
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e must be declared as two-byte integers (as “short” or “short int” de- 
pending on your site’s C implementation) 


¢ must be preceded by a colon (:) when used in a SQL statement 
e must not be preceded by a colon when used in a C statement 
° must not be a SQL reserved word (see Appendix C) 


e must be preceded by its associated input host variable in the SQL 
statement. 


For example, now we have added the two indicator variables DEPTNOI 
and NAMEI to the previous query: 


EXEC SQL SELECT DEPTNO, ENAME 
INTO :PDEPTNO:DEPTNOI, :PNAME: NAME 
FROM EMP 
WHERE EMPNO = :PEMPNO; 


Sce “Using Returned Values in Indicator Variables” for additional details 
on using Indicator Variables. 


Declaring Pointers as Host Variables 
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You can use pointer variables (simple pointers) in the DECLARE section 
by declaring them in the normal C manner, using an asterisk and variable 
name, as in the following example: 


EXEC SQL BEGIN DECLARE SECTION; 
int i, j, *intptr; 

char *cp; 

EXEC SQL END DECLARE SECTION; 


When used in a SQL statement, precede the variable name with a colon, 
not an asterisk, as the asterisk is implicit: 


SELECT INTFIELD INTO :intptr FROM... ; 


For all but char pointers, the size of the referenced object is given by the 
size of the base type specified in the declaration. For char pointers, the 
referenced object is assumed to be a null-terminated string, whose size is 
determined at runtime by invoking the string Jength function. 


Note that if a pointer to a char variable is used as an input host variable (in 
the USING clause), its length is still determined by a string length call. 











This may not produce the desired result, since it will yield the current 
length, not the maximum length. 


| 
| 
| 
Declaring the VARCHAR Pscudo-Type | 

Pro*C allows the use of the VARCHAR pseudo-type, to accommodate 

varying length character strings. It is only referenced within the DE- 

CLARE section, and can be thought of as an extended C type or prede- 

clared structure. The following declaration: 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR jobDesc[40]; 
EXEC SQL END DECLARE SECTION; 


can be expanded into the following structure variable: 


struct { 
unsigned /*2 bytes*/short int Ten; 
unsigned char arr[40] 
} jobDesc; 


The character array is declared with the size specified in the VARCHAR 
definition. The len field specifies the current length of the varying size 
string. 


VARCHAR variables, by definition, are never null-terminated. The len 
part of the VARCHAR structure contains the string length, and thus is set 
by ORACLE when used as an output variable. Len must be set by the us- 
er's program when used as an input variable, Any null values in the arr 
array are ignored or overwritten. 


Character strings may be defined in two ways: 


char str{100]; as a character array, or 
char *str; as a string pointer 


When used as an array, the length is determined by the string dimension 
(i.e. 100). For both input and output this is the accepted length. ORACLE 
will blank-pad the buffer on output, and it is up to the user’s program to 
blank-pad the string on input. 


VARCHAR variables are referenced in SQI. statements using the aggregate 
name, preceded. by a colon, just like other variables. For example, either 
of the following queries might follow the above declaration: 
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EXEC SQL SELECT JOBDESC INTO :jobDesc FROM EMP 
where empno = :empno; 


or: 


getSTring( jobDesc. arr); 

/* Get job description from user */ 

JobDesc. len = strlen(jobDesc.arr); 

/* Get length of string*/ 

EXEC SQL SELECT ... INTO ... FROM EMP 
WHERE JOBDESC = : jobDesc; 


When a VARCHAR is used as an output host variable (in the INTO 
clause), ORACLE RDBMS sets the length field. When used as an input 
host variable (in the WHERE clause), the program should set the length 
field. 


You can use VARCHAR *ID to declare pointers to VARCHAR 
datatypes. You can also use repeating definitions for standard C types, as 
in 


VARCHAR ID1[10], *ID2, ... , IDN[4] 
which is equivalent to: 


VARCHAR ID1[10]; 
VARCHAR ID2; 
VARCHAR IDN[4]; 
.. and so on 


The length of the string buffer when dealing with a pointer is specified by 
invoking the strlen() function. This works fine for input, and is convenient 
because the user program will not have to set len (VARCHARSs) or blank- 
pad a buffer (string arrays). Output, however, is a bit more complicated. 
Because ORACLE determines buffer length with strlen(), the length of the 
buffer it is not necessarily visible to the user. It is easier to declare and 
output buffer as a character array (str[100]) than as a character pointer. 


What is Prohibited from the Declare Section? 
Do not refer to names declared in typedef statements. Such names are un- 
known to Pro*C so their use results in undeclared variables and subsequent 
errors. 
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Do not refer to previously named structures. Similatly, you should not de- 
clare a variable to be of some structure type. You can use structures, 
however, in one of the following three ways: 


| e To copy data back and forth between structure elements and simple 
variables. 


| e ‘To access a field with type T, declare a variable of type *T in the 
DECLARE section. Then initialize the pointer with the address of the 
structure clement of interest. 


© To use descriptors and dynamic statements, which gives flexibility as 
to the location of host. variables. 


The Prologue: Declaring the SQL Communications Area 





Every Pro*C program must provide for event handling, by including in the 
Application Prologue a reference to the SQL Communications Area. You 
need only include one line: 





EXEC SQL INCLUDE SQLCA; 


EXEC SQL INCLUDE is used to include other files into your Pro*C 
program. The statement replaces the C #include convention for cross lan- 
guage compatibility. You may EXEC SQL INCLUDE files which them- 
selves have EXEC SQL INCLUDE statements, The number of levels 

| nested is limited by your operating system’s limit on open files. 


The INCLUDE statement should match the case (upper or lower) of the 
actual .h file (usually upper case). Pro*C must be able to locate the 
SQLCA file at precompile time, so you have three choices: 


© use the INCLUDE = cominand line option 


o fully qualify the filename so that Pro*C can find it in a common O/S 
area, as in (for VMS) SYSSORACLE:SQLCA 


e copy the SQLCA file into the directory or disk you will be invoking 
PCC from. f 


Jf you encounter problems, check with your DBA. 





| This statement directs Pro*C to include the SQL Communications Area in 
the program. The SQLCA may be included locally or globally. The 
SQLCA contains definitions of variables uscd to communicate with 
ORACLE. When the program is precompiled, ORACLE substitutes se- 
veral host language variable declarations in place of the INCLUDE state- 
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ment. These declarations enable ORACLE to interface with your program 
by passing information during program execution, about the status of vari- 
ous operations. The SQLCA includes information such as: 


e warning flags and event information 
e error codes 
e diagnostic text. 


For example, you can check to see if a SQL statement executed success- 
fully, and if so, how many rows were inserted or updated. Or, ifa statement 
terminated with an error, you can get more information about what hap- 
pened, 


Thus, the SQLCA gives the programmer the option of taking different 
actions, at various points throughout the program, based on feedback re- 
ceived from ORACLE about work just attempted. 


By default, a Pro*C program will ignore errors and continuc processing 
when possible. By using the variables included in the SQLCA, a pro- 
grammer can control the actions taken under certain circumstances. For 
example, with the WHENEVER declarative statement, you can indicate 
actions to be taken upon the detection of an error, a warning, or particular 
events. The actions can include stopping the program, branching, or con- 
tinuing, if possible. (The WHENEVER statement and options are dis- 
cussed in “The WHENEVER Statement”.) 


Though there are several variables in the SQLCA, we'll mention just two 
now: 


sqlca.sqlcode This variable holds a result code after the execution of every 
executable SQL statement. The code is an integer which indicates 
how the statement executed. A zero sqlca.sqicode indicates suc- 
cessful execution. A negative sqlca.sqlcode indicates one of the 
ORACLE errors, documented in ORACLE Error Messages and 
Codes. A positive sqica.sqlcode indicates successful execution, 
with a status code (such as end-of-file). Currently there is only 
one positive code: 1403, indicating “row not found”, or last row 
selected), 


sqlea.sqiwarn This variable is actually an array of eight warning flags. The 
first element, sqlca.sqiwarn[0], is set to “W” if any of the other 
flags is set, and so is a useful quick indicator of any problems. 


For a much more detailed discussion of error handling options available to 
the programmer, see the Chapter “Error Detection and Recovery”. "The 
Whenever Statement” describes the options available for the 











The ORACA, an Extension to the SQLCA 





Precompiler users have requested the ability to obtain more information 
from the precompiler’s runtime environment than is available in the SQL 
Communications Area (SQLCA). However, as the SQLCA is intended to 
be “standard SOL”, Version 1.0 introduces an ORACLE Communications 
Area, the ORACA. 


The ORACA can only be used if the definition of ORACA is INCLUDED 
by using an EXEC SQL INCLUDE statement, and if the option 
ORACA= YES is selected, either as a command line option or via the 
EXEC ORACLE OPTION. 


Information in the ORACA 





The ORACA includes the following information. 


current SQL statement text(orastxt) Useful especially when errors are en- 
countered, you can retrieve the text of statements which are parsed 
by ORACLE RDBMS (the statements associated with cursors). 
Statements parsed by the precompiler (such as CONNECT, 
FETCH, COMMIT) will not appear in the ORACA. At most, 
the first 70 characters of the SQL statement will be displayed in 
the ORACA. The format of the SQI statement is the same as for 
the error message in the SQLCA. 


filename with error(orasfnm) If multiple files are precompiled for one ap- 
plication, the ORACA will identify in which file the error oc- 


curred, 
line number with crror(oraslnr) Identifies the line number in the file. 


The ORACA also includes the following flags, which you can use to pass 
runtime options to the ORACLE Programmatic Interfaces: 


save SQL statement when(orastxtf) You can choose which conditions will 
save the statement by setting this flag to: 


0 The default: never save the 
SQL statement. 


l Save SQL statement on 
SQLERRORs only. 
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ORACA Features New in V1. 
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2 Save SQL statement on 
SQLERROR or SQLWARN. 


3 Always save the SQL state- 
ment. 
enable DEBUG operations This flag can be set to 0 or 1. If set to 


1 it enables all DEBUG operations 
(currently, only the flag for checking the 
cursor cache, described next). Default 
is off (0). 


check cursor cache(orahchf) If set to | (and if the master debug flag 
is also enabled - set to 1), then the gen- 
erated code will check the cursor cache 
for consistency before every cursor op- 
eration, and if an error is detected one 
of the OFR(21xx) errors will be gener- 
ated. The default is 0, for normal 
checking. 


it 

Version 1.1 introduces several new variables in the ORACA. As with 
other ORACA info, ORACA = YES must be selected either on the PCC 
command line or via EXEC ORACLE OPTION, and the ORACA must 
be INCLUDEd. 


All existing programs that use the ORACA must be re-precompiled to use 
Version 1.1. 


orahchf (Check Heap Consistency Flag) If set (not zero), it generates heap 
consistency checks for all dynamically allocated memory owned 
by the PCC. Useful for detecting user bugs that upset memory. 
ORADBGF must also be set non-zero. 
Cursor cache statistics. The following flags essentially make available in- 
formation that heretofore was only provided in C via sqlpes() 
(Print Cursor Statistics). 
orahoc Highest Maximum Open OracleCursors requested. 
oramoc Maximum OracleCursors required. 
oracoc Current number of OracleCursors. 
oranor Number of cursor cache reassignments. 


oranpr Number of SQL statement “parses”. 


| 
| 














oranex Number of SQL statement “executes”. 


These variables are set at runtime by every COMMIT or 

ROLLBACK. There is one set of these variables (internally) for 
every database. T herefore, the current values in the ORACA are 
those for the processes’ last COMMIT/ ROLLBACK, on a given 


database. 


Enabling the ORACA 





The use of the ORACA is optional, for reasons of efficiency. To use the 
ORACA, you must: 
1. Use a new command line option: ORACA#= YES (default is NO) 


2. Add the following line to your program using syntax appropriate for 
your language: 
EXEC SQL INCLUDE ORACA 
3. Set the desired flags in the ORACA to choose options. 


WHENEVER statement, and “The SOLCA Structure” describes the cight 
variables contained in sqlca.sqlwarn. 


The Prologue: Connecting to ORACLE 


Every Pro*C program must connect to the ORACLE RDBMS before it 
can successfully access any ORACLE data. To connect, simply use the 
SQL, CONNECT statement preceded with the EXEC SQL phrase: 


EXEC SQL CONNECT ;:oracleid IDENTIFIED BY :oraclepassword; 


or 


EXEC SQL CONNECT :oracleid /* where oracleid = scott/tiger xy 


Note that: 


© The CONNECT statement must be the first executable SQL state- 
ment to be executed in the Pro*C program. Only declarative state- 
ments and C code may logically precede the CONNECT statement. 
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° Ifthe password is supplied separately, then host variables must be used 
for both the ORACLE username Coracleid) and ORACLE password 
(oraclepassword) 


° Both host variables should be declared as fixed-length or variable 
character strings. Fixed length strings should be padded on the right 
with blanks (to 20 characters). 


e Both host variables should be initialized before the CONNECT state- 
ment is executed, or the CONNECT will fail. 


e ‘Though the CONNECT is the first executable statement in a program, 
it does not start a logical unit of work. The next executable statement 
encountered in the program will start the logical unit of work. 


To initialize the two host variables, the programmer can either embed. the 
values for the ORACLE username and password into the program, or code 
the program to prompt, via the terminal, for a valid username and pass- 
word. 


See Figure 3 on page 7 for a list of the SQL declarative statements. 


Connecting via Automatic Login 


Connecting via SQL*Net 
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If you wish to take advantage of the automatic login feature of ORACLE 
(using ORACLE usernames prefixed by OPS$), you simply pass to Pro*C 
a string containing a slash ee. 


VARCHAR oracleid[ 20]; 
strcpy(oracleid.arr, "/"); 
oracleid.len = strlen(oracleid.arr); 


EXEC SQL CONNECT :oracleid; 


Pro*C supports access to other machines and databases on those machines 
through the product SQL*Net. For example: 


EXEC SQL CONNECT :usr IDENTIFIED BY : pwd 
where: 


char userid[20] = "scott@d:750vms-t" 
char pwd[20] = "tiger"; 














This example allows all further ORACLE action within this program to 
take place against another database. However jt limits you to one connect 
statement and only one database. 


If you wish to access multiple databases within the same program the form 


changes. For example: 


E SQL BEGIN DECLARE... 
char host1[20] = " d:750vms~t: 


L$} 


char host2[20] = " d:750vms-p: 
E SQL END DECLARE... 
EXEC SQL DECLARE ORA1 DATABASE; 
EXEC SQL DECLARE DB2 DATABASE; 
EXEC SQL DECLARE CONNECT 
¿usr IDENTIFIED BY :pwd 
AT ORA1 USING : host]; 
AT DB2 USING : host2; 


In this example, ORAL and DB2 are simply logical names used by the 
connect statements. The USING clause actually specifies the network, 
machine and data base to be associated with the name ORAI or DB2. As 
with cursor and statement names, ORAI and DB2 are not host variables, 
but an identification name given for case of use. 


THE APPLICATION BODY 


The Application Body contains SQL statements to query and manipulate 
the data stored in an ORACLE database. Those statements are called Data 
Manipulation statements (or DML, for Data Manipulation Language). The 
application body may also contain Data Definition statements (DDL), 
which are used to create or define data structures, such as tables, views, or 
indexes. ‘ 


In this document, we first discuss SQL statements which do INSERT, 
UPDATE, or DELETE operations, because they are conceptually easiest. 
(Rather than returning rows of data, these rows simply return a code de- 
noting success or failure of the operation. The number of rows processed 
is available in the SQLCA.) 
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Then we progress to queries (SELECT statements), which can be further 
qualified as 


® queries which return only one row, or 
e queries which return more than one row. 


The latter type of query requires the use of a cursor, which will be described 
in “Using Cursors”. 


Finally, we discuss a type of SQL statement called dynamically defined 
Statement. Dynamically defined SQL statements can change from exe- 
cution to execution, and though most complex to understand or code, are 
very flexible and allow the coding of very diverse, flexible applications. 
“Dynamically Defined Statements’ illustrates the use of dynamic SQL 
statements within programs. Note that dynamically defined statements can 
be grouped into two classes: those of a known structure, which use im- 
mediate execution, and those of an unknown structure, which use prepare. 
Both immediate execution and prepare are described in Chapter 6. 


The Statement DECLARE STATEMENT 
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A new statement, similar to DECLARE CURSOR, is available: 


EXEC SQL DECLARE s STATEMENT; 


which can be used to control definition statements. For example, the fol- i 
lowing C code segment was not valid in earlier versions of the precompilers: | 


main() 


init(); 
execute(); 


execute() 

EXEC SQL EXECUTE S; 
} 

init() 


EXEC SQL PREPARE $ FROM 
"INSERT INTO EMP (ENAME) VALUES ('WILMA')"; 
} 











because when the EXECUTE S was encountered, the statement S was 
undefined (i.e., the statement S was defined by the PREPARE). In Version 
1 Pro*C, you can insert the following statement into the main() program, 
and. the program will work: 


EXEC SQL DECLARE $ STATEMENT; 


The Statement DECLARE DATABASE 





The statement 
EXEC SQL DECLARE ORA1 DATABASE 


is used with SQL*NET to connect to and issue actions against other data- 
bases. 


The EXEC ORACLE Options 





The EXEC ORACLE OPTION statement allows you to specify options 
inline which previously could be specified only at runtime. The options 
may now be specified both at runtime and inline, thus allowing you to dy- 
namically change settings throughout the program. To see a list of options 
that can be specified using EXEC ORACLE OPTION, type PCC <er>. 
The options that are marked with an asterisk can be specified inline, 


EXEC ORACLE OPTION ( option=option_arg ); 
Those options are: 
o ARBASIZE 
e ERRORS 
e INCLUDE 
e = LITDELIM 
e MAXLITERAL 
e MAXOPENCURSORS 
° REBIND 
e SELECT_ERROR 
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e XREF 


For example, now you can change the AREASIZE on a cursor-by-cursor 
basis, as in: 


EXEC ORACLE OPTION ( AREASIZE=4 ); 
EXEC SQL SELECT ENAME 
INTO :ename 
FROM EMP; 
EXEC SQL DECLARE C1 CURSOR FOR SELECT ENAME FROM EMP; 
EXEC ORACLE OPTION (AREASIZE=8 ); 
EXEC SQL OPEN C1; 


In this example, the first statement is opened with a cursor size of 4K, but 
the second statement is opened with a cursor size of 8K. Even though 
cursor allocation is dynamic, this option allows you to change the base al- 
location for different SQL statements. 


The EXEC ORACLE OPTION statement also helps alleviate problems 
on some operating systems which have limits on the number of characters 
which can appear in a command line. 


An option entered inline will override the same option entered on the 
command fine. You can also place EXEC ORACLE options in a separate 
file and EXEC SQL INCLUDE them at the appropriate place in the pro- 
gram. 


The Array BIND/FETCH Feature 





Array Fetches 


Beginning with V1 of Pro*C, you can perform DML statements using host 
variable arrays. This means that rather than only using variables declared 
as single values (scalars), as in V4 ORACLE PCC, Pro*C accepts host 
variables declared as arrays for use in INSERT, UPDATE, and SELECT 
statements. 
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Following are some code segments to briefly demonstrate the use of three 
arrays (ENAME, EMPNO, and SAL.) to select up to 100 names. Using 
the same DECLARE section, two different examples of the SELECT are 
shown, 














EXEC SQL BEGIN DECLARE SECTION; 
char ename [100] [10]; 
int empno [100]; 
float sal [100]; 
EXEC SQL END DECLARE SECTION; 
Example A 


EXEC SQL SELECT ename, empno 
INTO :ename, :empno 
FROM EMP; 


Example B 


EXEC SQL DECLARE C1 CURSOR FOR 

SELECT ename, empno 

FROM EMP; 

EXEC SQL OPEN C1; 

EXEC SQL WHENEVER NOT FOUND GOTO.. 
EXEC SQL FETCH C1 INTO :ename, :empno; 


Example A shows a multi-row SELECT directly into the two host variable 
arrays. Assuming there are less than 100 rows, or you only want to see 100 
rows, this will work without using cursors. If you want to fetch more than 
the 100 rows, you would use Example B and execute the FETCH multiple 
times until an END-OF-FETCH. If there are more than 100 rows, and 
you re-execute the SELECT in Example A, you will still retrieve just the 
first 100 rows. To see past the first 100 rows, you need to use a multi-row 
SELECT (with a cursor), but you actually fetch in 100 row “batches”. 


Restrictions on Array Fetches 


One restriction is imposed on SELECT statements with host variable ar- 
rays. In a SELECT statement, a WHERE clause can never contain an ar- 
ray; this would create an ambiguous case and is therefore invalid. If you 
should use an array in a WHERE clause, the resulting error is: 


array not legal in WHERE clause 
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Array Binds 





The following table shows which uses are valid and which are not. 


SELECT ...INTO...... WHERE ..... VALID? 
array array no 
scalar scalar yes 
array scalar yes 
scalar array no 


Note that, used properly, you can use arrays in WHERE clauses in UP- 
DATE statements (see the next section). 
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The previous examples demonstrated array fetches; you can also bind array 
variables for use in DML statements (INSERT and UPDATE). The fol- 

lowing example assumes the same declaration section as used in Examples 
A and B: 


EXEC SQL INSERT INTO EMP (ENAME, EMPNO, SAL) 
VALUES (:ename, :empno, :sal); 


(This also assumes that the arrays (cname, cmpno, and sal) have been 
populated prior to the insert statement.) 


UPDATE statements also allow the use of host variable arrays, but with 
some restrictions. You may use arrays in the SET clause as long as the 
WHERE clause is also an array. You may not mix host variable arrays and 
single variables (scalars) in an UPDATE statement. For example: 


EXEC SQL UPDATE EMP SET SAL = :sal WHERE EMPNO = :empno; 


In this case, the two host variables could either be scalar or array, but their 
types must match. If sal were defined as a 100-clement array, then empno 
must be defined to be the same array size. (Though variable types must 
match, data types need not; for example, you could update records selected 
based on 100 numbers to have 100 new dates.) 











The following table shows which uses are valid and which are not. 


UPDATE ...SET....... WHERE ..... VALID? 
array array yes 
scalar scalar yes 
array scalar no 
scalar array no 


In the case that both host variables are arrays, the statement is equivalent 
to 


for (i=0; i<= max_array_index; i++) 
update emp set sal = sal[i] where empno = empno[i]; 


This steps through both arrays by bumping up to the next element in each 
array. 


General Caution about Arrays 


If you use more than one host variable array in a SQL statement, and the 
arrays are of different dimensions, Pro*C generates the warning: 


ARRAY SIZE MISMATCH 


at precompile time. However, this is only a warning message. Pro*C uses 
the smaller of the arrays as the number of elements to use in the statement. 


Pro*C V1 will detect illegal update clauses for non-dynamic SQL state- 
ments. However, it is up to the programmer to check for valid usage in 
dynamic SQL statements. 
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Using the FOR Statement to BIND/FETCH Arrays 


The keyword FOR may be used in Pro*C to set the number of elements 
to be used in a host variable array. This is useful if you wish to execute a 
SQL statement for only a portion of any array. Por example; 


EXEC SQL BEGIN DECLARE SECTION; 
int empno[ 100]; 
int loop; 

EXEC SQL END DECLARE SECTION; 


Joop=50; /* set loop to half of the array */ 
EXEC SQL FOR :loop SELECT EMPNO INTO :empno FROM EMP; 


The FOR statement will override the actual number of elements in the ar- 
rays in question, so be careful that you do not specify a number larger than 
the actual array size. 


WARNING: This could cause the program to write over other data areas 
within the program and end abnormally. 


USING THE FOR CLAUSE TO UPDATE AND INSERT STATEMENTS 





The FOR clause is especially useful in UPDATE and INSERT statements. 
With these statements you may not wish to use the cntire array (the de- 
fault). With FOR, you can limit the elements used to just the number you 
want. 
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EXEC SQL WHENEVER NOT FOUND CONTINUE; 


10; /* nr of rows to fetch in each block */ 
0; /* nr of rows fetch'd last time */ 
0; /* nr of rows fetch'd this time */ 


rows_to_fetch 
rows_last_time 
rows_this_time 


ui H 


do 
{ 
EXEC SQL FOR :rows_to_fetch FETCH...; 


sqica.sqlerrd[2] - rows_last_time; 


rows_this_time 
sqica.sqlerrd{ 2]; 


rows_last_time = 
if ( rows_this_time != 0 ) 
{/* Fetch'd something, so need to INSERT these rows. */ 
EXEC SQL FOR :rows_this_time INSERT...; 


} 


} while ( rows_this_time == rows_to_fetch ) 
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SAMPLE PRO*C PROGRAMS 


Note that updated/corrected versions of the examples shown in this manual 
are provided on the distribution tape. You may find that the examples on 
the tape vary slightly from those presented in the documentation. 


Logging in and out of ORACLE 
The first example is the most basic Pro*C program: simply logging in and 
out of ORACLE. 


/* Example #1 */ 
#include <stdio.h> 





This is a sample Pro*C program which will log onto 
a database as scott/tiger. 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[ 20]; 
VARCHAR pwd[ 201; 

EXEC SQL END DECLARE SECTION; 

EXEC SQL INCLUDE SQLCA; 


| main() 
| /* log into ORACLE */ | 
| strepy(uid. arr," SCOTT"); /* copy the user name */ | 
| uid. len=strlen(uid.arr); ; 
| strcpy( pwd. arr," TIGER"); /* copy the password */ | 
| pwd. len=strlen(pwd. arr); 

EXEC SQL CONNECT :uid IDENTIFIED BY :pwd; 

printf("Connected to ORACLE user:%s\n",uid.arr); 

EXEC SQL COMMIT WORK RELEASE; /* log off database */ 

exit(0); 

} 
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Creating a Table 





In this example, we create a table named EMP_TEST, with columns 
EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, and DEPTNO. 


/* Example #2 */ 
#include <stdio.h> 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[20]; 
VARCHAR pwdf 201; 

EXEC SQL END DECLARE SECTION; 

EXEC SQL INCLUDE SQLCA; 


main() 
/* Jog into ORACLE */ 
strcepy(uid.arr, "SCOTT"); /* copy the user name */ 
uid. len=strlen(uid. arr); 
strcpy(pwd.arr, "TIGER" ); /* copy the password */ 


pwd. len=strlen(pwd.arr); 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 
printf("Connected to ORACLE as user: %s \n",uid.arr); 
EXEC SQL CREATE TABLE EMP_TEST 

(empno number,ename char(15),job char(10), 

mgr number, hiredate date,sal number,deptno number); 
printf("Table emp_test created. \n"); 


EXEC SQL COMMIT WORK RELEASE; /* log off database */ 
exit(0); ; 
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Prompting for Values to Insert Rows 


This example demonstrates insertion of a row into a table, by prompting 
the user for records to be inserted. 
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/* Example #3 */ 
#include <stdio.h> 


This is a sample Pro*C program which will insert records 
into the EMP table by prompting the user for values to be entered, 
EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
int empno; 
VARCHAR ename[ 15]; 
VARCHAR job[ 10]; 
float sal; 
int deptno; 
EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


main() 


int sret; /* return code from scanf */ 


/* Jog into ORACLE */ 

strcpy(uid, arr, "SCOTT" ); /* copy the user name */ 
uid, len=strlen(uid.arr); 

strcpy(pwd. arr, "TIGER" ); /* copy the password */ 
pwd. len=strlen(pwd.arr); 


EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 
printf("Connected to ORACLE as user:%s \n\n\n",uid.arr); 


oe (1) 


printf("Enter employee number (or 0 to end): "); 
sret = scanf("%d", &empno); 
if (sret == EOF !! sret == 0 !! empno == 0) 
break; /* terminate loop */ 
printf("Enter employee name: "); 
scanf("%s",ename.arr); 
ename, len=strlen(ename.arr); /* set the name size */ 
printf("Enter employee's job: "); : 
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scanf("%s", job. arr); 

Job. len=strlen(job.arr); /* set the job size */ 
printf("Enter employee salary: "); 

scanf("%Ff",&sal); 

printf("Enter employee deptno: "); 


scanf("%d" ,&deptno); 


EXEC SQL INSERT INTO EMP 

(empno,ename, job, sal,deptno) 

VALUES(: empno,:ename,:job,:sal,:deptno); 
EXEC SQL COMMIT WORK; 


printf("Employee %s added. \n\n",ename.arr); 


EXEC SQL COMMIT WORK RELEASE; /* log off database */ 


exit(0); 
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Using Arrays to Insert from a File 


This example program reads data from a file and inserts it, using arrays, into 
an existing table. 





$ 
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/* Example #4 */ 
#include <stdio.h> 


EXEC SQL BEGIN DECLARE SECTION; 


This is a sample Pro*C program which uses the FOR option 

by inserting records into the EMP table. 

This is done by reading data from a file, putting it 

into arrays, and inserting from those arrays. 

The data in the file will be in character format and separated 
by spaces. This will allow the use of fscanf on the line. 





VARCHAR uid[ 20]; 

VARCHAR pwd 20]; 

int empno[ 100]; 

VARCHAR enamel 100][15]; 
VARCHAR job[100][ 10]; 
VARCHAR hiredate[100][9]; 
float sal[100]; 

int deptno[ 100]; 

int loop; 


EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


FILE *fp; /* file pointer */ 
main() 
int 4; /* array counter */ 
int fsret; /* fscanf return code */ 
/* log into ORACLE */ 
strcpy(uid.arr, "SCOTT"); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd.arr, "TIGER" ); /* copy the password */ 


pwd. len=strlen(pwd.arr); 


EXEC SQL WHENEVER SQLERROR GOTO errrpt; 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


printf("Connected to ORACLE as user: %s \n",uid.arr); 
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if ((fp= fopen("test.dat","r")) == NULL) 
f 


printf("Error opening file test.dat. \n"); 
exit(1); 
3 


while(1) /* do this for a long time */ 
for(i=0;i < 100; i++) /* this will go 0 - 99 */ 


{ 
fsret=fscanf(fp,"%d %s %s %s %f 4d", 
&empnoFis, enamel i].arr,jobli].arr,hiredate[i].arr, 
&salli],&deptno[i]); 
if (fsret == EOF) 
break; /* tess than 100 to read */ 
if (fsret == 0) /* found an error in the line */ 


printf("Incompatible field on the line. \n"); 
exit(1); 


} 


ename[ i]. len=strlen(ename[i].arr); 
job[ i]. len=strlen(job[i].arr); 
hiredate[ i]. len=strlen(hiredate[ i].arr); 


} 
loop = 1; 
EXEC SQL FOR : loop 


INSERT INTO EMP (empno,ename, job, hiredate, sal,deptno) 
VALUES (:empno, :ename, : job, :hiredate, : sal, :deptno); 


/* set for loop iterations */ 


EXEC SQL COMMIT WORK; 
printf("%d rows inserted. \n",sqlca.sqlerrd[2]); 


if (loop < 100) /* this is last time */ 
break; /* in the loop so exit */ 


} 


printf("File test.dat loaded. \n"); 
EXEC SQL WHENEVER SQLERROR CONTINUE; 
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EXEC SQL COMMIT WORK RELEASE; /* log off database */ 
exit(0); 


errrpt: 
printf("\n %.70s \n", sqlca. sqlerrm. sqlerrmc); 
EXEC SQL ROLLBACK WORK RELEASE; /* log off database */ 
exit(1); 
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Prompting for Values Used in an Update 





In this example of an update, we first prompt for the name of the employee 
whose record will be changed, and then we prompt for the changed values. 
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/* Example #5 */ 
#include <stdio.h> 


This program is an example of Pro*C which will prompt the user 
for an employee name and will display the current sal and comm 
fields for that employee. Then it will prompt the user for the 
new salary and commision and will update the emp table for 
that employee. 


RS SSS SSS RS SSS SSSR SSS SE SRS Sec / 


EXEC SQL BEGIN DECLARE SECTION; 


VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
VARCHAR ename[ 10]; 
float sal,comm; 
short sali,commi; 


EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


main() 


int sret; /* scanf return code */ 


/* log into ORACLE */ 


strepy(uid. arr, ""SCOTT"); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd. arr," TIGER"); /* copy the password */ | 


pwd. len=strlen(pwd.arr); 


EXEC SQL WHENEVER SQLERROR STOP; 
EXEC SQL WHENEVER NOT FOUND STOP; 
EXEC SQL CONNECT :uid IDENTIFIED BY :pwd; 


printf("Connected to ORACLE user: %s \n",uid.arr); | 
printf("Enter employee name to update: "); 
scanf("%s",ename.arr); 


ename. len=strlen(ename.arr); 


EXEC SQL SELECT SAL,COMM INTO :sal,:comm FROM EMP 
WHERE ENAME=: ename; 
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printf("Employee: %s sal: %6.2f comm: %6.2f \n" ,ename.arr,sal,comm); 


printf("Enter new salary: "); 
sret=scanf("%f",&sal); 


sali = 0; /* set indicator */ 
if (sret == EOF !! sret == 0) 
sali=-1; /* set indicator for NULL */ 
printf("Enter new commision: "); 
sret=scanf("%f", &comm); 
commi = 0; /* set indicator */ 
if (sret == EOF !! sret == 0) 
commi=-1; /* set indicator for NULL */ 


EXEC SQL UPDATE EMP SET SAL=:sal:sali,COMM=:comm:commi 
WHERE ENAME=: ename; i 


printf("Employee %s updated. \n",ename.arr); 


EXEC SQL COMMIT WORK RELEASE; 
exit(0); 
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Updating Using Arrays 
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This sample program prompts for employee numbers and new salaries and 
then performs the updates using arrays. 








IONN 


/* Example #6 */ 
#include <stdio.h> 





This is a sample Pro*C program which updates using host 
variable arrays. The arrays will be loaded with values 
from operator input. 


NOTE: Following the rules on arrays in UPDATE statements, 
both the SET and WHERE host variables must be the same 
type, either array or scalar. 


EXEC SQL BEGIN DECLARE SECTION; 


VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
int empno[ 100]; 
float sal[100]; 
int loop; 


EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


matn() 


int 4; /* array counter */ 
int sret; /* scanf return code */ 


/* Jog into ORACLE */ 

strcpy(uid.arr,"SCOTT"); 
uid. len=strlen(uid. arr); 
strcepy( pwd. arr," TIGER"); 
pwd. len=strlen(pwd.arr); 


EXEC SQL WHENEVER SQLERROR GOTO errrpt; 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


/* copy the user name */ 


/* copy the password */ 


printf("Connected to ORACLE as user:%s \n",uid.arr); 
while(1) /* do this for a long time */ 


for(i=0; i < 100; i++) /* this will go 0 ~ 99 */ 
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printf("Enter employee number (or 0 to end loop): "); 
sret=scanf("%d", &empno[i]); 
if (sret == EOF !! sret == 0 !! empnofi] == 0) 

break; 
printf("Enter updated salary: "); 
sret=scanf("%f", &salL iz); 
if (sret == EOF !! sret == 0) 


printf("Error in entry; terminating at this empno.\n"); 


break; 
} 
} 
if (i == 0) /* end completely */ 
break; 
loop = 4; /* set for loop iterations */ 


EXEC SQL FOR : loop 
UPDATE EMP SET SAL = :sal WHERE EMPNO = :empno; 


EXEC SQL COMMIT WORK; 

printf("%d rows updated. \n",sqlca.sqlerrd[2]); 
} | 
printf("Update program complete, \n"); 


EXEC SQL WHENEVER SQLERROR CONTINUE; /* don't trap next errors */ 
EXEC SQL COMMIT WORK RELEASE; /* log off database */ 


i 
| 
| 
| 
| 
i 
i 
i 


exit(0); 
errrpt: 
printf("\n %.70s \n",sqlca.sqlerrm. sqlerrmc); 
EXEC SQL ROLLBACK WORK RELEASE; /* log off database */ 
exit(1); 
} 
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Selecting Using Arrays 


This sample program shows a query returning three columns of a table, 
through host variable arrays. 
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/* Example #7 */ 
#include <stdio.h> 


This is a sample Pro*C program which selects using host 
variable arrays. 


NOTE: Following the rules on arrays in SELECT statements, 
the WHERE clause may not contain host variable arrays, on 
scalar-type host variables (single-value variables). 
EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
int empno[ 100]; 
VARCHAR e 100] 18); 
float sal[100]; 
EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


main() 
Tong num_ret; /* number of rows returned */ 
/* log into ORACLE */ 
strcpy(uid.arr,"SCOTT"); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd.arr, "TIGER"); /* copy the password */ 


pwd. Ten=strlen(pwd.arr); 


EXEC SQL WHENEVER SQLERROR GOTO errrpt 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


printf("Connected to ORACLE as user: %s \n",uid.arr); 


EXEC SQL DECLARE C1 CURSOR FOR 
SELECT EMPNO, ENAME, SAL FROM EMP 
EXEC SQL OPEN C1; 
EXEC SQL WHENEVER NOT FOUND GOTO endloop; 
num_ret = 0; /* intialize number of rows */ 
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endloop: 


errrpt: 


} 


while(1) /* do this for a long time */ 
EXEC SQL FETCH C1 INTO :empno,:ename, :sal; 


print_rows(sqica.sqlerrd[2] ~ num_ret); 
num_ret = sqlca.sqlerrd[2]; /* reset number */ 


if (sqlca.sqlerrd[2] - num_ret > 0) 
print_rows(sqica.sqlerrd[2] - num_ret); /* call last time */ 


printf("\n\nProgram complete. \n"); 

EXEC SQL WHENEVER SQLERROR CONTINUE; 

EXEC SQL COMMIT WORK RELEASE; /* log off database */ 
exit(0); 


printf("\n %.70s \n",sqlca.sqlerrm. sqlerrmc); 
EXEC SQL ROLLBACK WORK RELEASE; 
exit(1); 


print_rows(n) 


long n; 


{ 


long 1; /* use a loop counter */ 


printf("\n\nEmployee number\tEmployee Name\tSalary\n"); 
printf ('\n\nrwrr rnc ere nen A a a Noina \n"); 


for(i=0; i<n; i++) 
printf("%15d\t%13s\t%6.2f\n", empno[i],ename[i].arr, salik); 


return; 
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Deleting a Row from an Existing Table 





This example demonstrates deleting a row, having prompted for the em- 
ployee number of the record to be deleted. 
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/* Example #8 */ 
#include <stdio.h> 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
int empno; 

EXEC SQL END DECLARE SECTION; 

EXEC SQL INCLUDE SQLCA; 


main() 
/* log into ORACLE */ 
strcpy(uid. arr, "SCOTT" ); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd.arr, "TIGER" ); /* copy the password */ 


pwd. len=strlen(pwd. arr); 


EXEC SQL WHENEVER SQLERROR STOP; 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


printf("Connected to ORACLE user: %s \n" uid. arr); 


printf("Enter employee number to delete: "); 
scanf("%d", &empno); 


EXEC SQL DELETE FROM EMP WHERE EMPNO = : empno; 
EXEC SQL COMMIT WORK RELEASE; /* log off database */ 


printf("Employee number %d dropped. \n", empno); 
exit(0); 
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CHAPTER 3. QUERIES 
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PARTS OF A QUERY 


This chapter introduces the concept of cursors, which are used to return the 
results of most queries. After the various cursor commands are introduced, 


two example programs are included. 


Queries may be the most interesting and useful type of DML statement. 
However, because we are not interested in just the transaction’s success or 
failure, but also in its results (a table of varying number of rows and col- 
umns), queries usually require additional coding. In the simplest cases, 
when a query returns one row, it can be coded like the simple programs in 
the last chapter. More often, however, a query is known to return several 
rows, or the number of rows in the result cannot be guaranteed to be only 
one. If more than one row will be returned, then a cursor should be used, 
and the use of a cursor requires additional Pro*C calls. (If a query is coded 
to return only one row and actually could return several, only the first row 


is returned.) 


In this chapter we'll first discuss queries which are known to return one 
row; then we'll discuss cursors, and their use, in queries which may return 


more than one row. 


Queries coded in Pro*C may contain any SQL SELECT statement, in- 
cluding the following clauses: 
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Input Host Variables 


SELECT 
INTO 
FROM 
WHERE 
CONNECT 
UNION 
INTERSECT 
MINUS 
GROUP BY 
HAVING 
ORDER BY 


(Of these keywords, all may be used in SQL*Plus, except INTO, which 
may be used in the precompiler, SQL*Forms, and Pro*SQL.) Consider the 
example: 


EXEC SQL SELECT ENAME, SAL + 1000, JOB 
INTO :ENAME, :SAL, :JOB 
FROM EMP 
WHERE EMPNO = : EMPNO; 


The fields (ENAME, JOB) or expressions (SAL + 1000) following the 
SELECT keyword are the items which make up the SELECT list. So our 
SELECT list contains three items. Based on the selection criteria specified 
in the WHERE clause (and following clauses, if present), ORACLE will 
return one row into the variables specified in the INTO clause (:ENAME, 
‘SAL, JOB). 


The number of variables in the SELECT list should equal the number of 
host variables specified in the INTO clause, so that there is a place to put 
every returned value. If the two lists have unequal numbers of items, the 
smaller number will be returned, and sqlca.sqlwarn[3] will be set to “W”, 
(See the description of sqlca.sqlwarn[3] in “The Meaning of SQLCA’s In- 
dividual Elements”.) 
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Host variables in the WHERE clause are called input host variables because 
they furnish information needed before processing the query. To bind a 
variable is to make its address known to the ORACLE RDBMS. For ex- 
ample, the value of the input host variable PEMPNO can be passed by 
parameter in the C program, or prompted for at execution time. These 











Output Host Variables 


variables are also called bind variables or using variables. T! hey can be used 
where constants can be used. 





Host variables in the INTO clause are called output host variables because 
they will hold the results of the SELECT statement after execution. These 
variables are also called define variables or into variables. 


(If a query returns more than one row, however, the INTO clause is not 
used as part of the select statement; instead, you declare a cursor which is 
used to pass the query’s results. See “Queries Which Return Multiple 


Rows”.) 


QUERIES WHICH RETURN A SINGLE ROW ONLY 


If you know your query will return only one row, you can use the INTO 
clause with as many output host variables as there are items in the SE- 
LECT list. For example, if you are querying for records based on a value 
in a unique index, you are guaranteed either one match (or none), as in: 


SELECT ENAME, SAL, JOB, MGRNO 
INTO :ONAME, :OSAL, :0JOB, :OMGR 
FROM EMP 

WHERE SSNO = 130443139; 


where “SSNO” is a numeric column of social security values, known to 
have unique values. 

If more than one row satisfies the criteria of the query and. 

SELECT ERROR is set to NO, then only the first row is returned. If 


SELECT ERROR is set to YES (the default) Pro*C will give an error 
(OER2112) if more than one row could be returned. See Chapters 2 and 


7 for additional information. 
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DATA CONVERSION 








Before delivering each SELECT list of values to the associated host vari- 
ables, ORACLE RDBMS converts the data value, if necessary, to the 
datatype of the host variable. Conversion may also occur when ORACLE 
RDBMS moves values from column to column, or from an input host 
variable to a column. 


Regardless of datatype, if a NULL value is returned to an output host 
variable, the indicator variable is set to -1. If there is no associated indicator 
variable, the SQLCODE is set to -1405. 


The following paragraphs describe how conversion works, and things to 
watch for. 


Converting Numeric Data 
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When converting numeric data, the following will cause no error or warn- 
ing: 


° truncation of zeroes on the left 
° truncation of fractional part of decimal or floating point numbers. 


Any other loss of information is considered an “error”, as described in the 
following sections. 


Conversion to integer values: Conversion of numetic to integer data is done 
by truncation. Truncation is toward zero; that is, all losses are on the right, 
and there is no warning that the fractional part is truncated. For example, 
4.55 is truncated to 4. Overflow occurs if the magnitude of the numeric 
data exceeds the size declared for the output host variable. (SQLCODE is 
set to a negative number.) 


Conversion to floating point: Conversion of numeric to floating point data 
attempts to fit the numeric data into the precision and scale of the output 
host variable. Significant digits are lost if the number of significant digits 
in the output host variable is smaller than in the actual data value, Over- 
flow occurs if the magnitude of the numeric data exceeds either the fraction 
and exponent declared for the output host variable. (SQLCODE is set to 
a negative number.) On underflow, the floating point variable is converted 
to zero. 








—SS 








Conversion to Character: When converting numeric data to character, 
ORACLE RDBMS converts the number to a character string, truncating 
on the right if necessary (following character string standard truncation 


guidelines). 


Converting Character Data 





Conversion Errors 


If the character data translates to valid numbers, ORACLE RDBMS first 
performs the conversion to numeric data, and then follows the guidelines 
in the previcus section to convert the numeric data to integer, or floating 


point numbers. 


If the original character data does not convert to numeric data, the 
SQLCODE is set to 1722. , 





When a conversion error occurs, the value of the output host variable is 
unpredictable. Therefore, if you are doing your own error handling (versus 
WHENEVER statements), you should always check the SQLCODE after 
executing a SQL statement 

For example, if a data value is too large for successful conversion (as when 
the decimal value is larger than the largest representable integer), ORACLE 
RDBMS returns a negative SQLCODE in the SQLCA, indicating a nu- 
meric overflow error. 


QUERIES WHICH RETURN MULTIPLE ROWS 


If your query may return more than one row, or you do not know how 
many rows ‘t will return, you must use a cursor along with the SELECT 
statement. The following sections describe the use of cursors. 
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USING CURSORS 





A cursor is a work area used by ORACLE and Pro*C, to contain the re- 
sults of a query. One (named) cursor is associated with one select state- 
ment, and may be executed repeatedly for different variations of the query 
(using different bind variables). 


A cursor must first be declared (associated with a query). Then, you use 
three executable SQL statements to use the cursor to manipulate the data. 
Thus, there are four cursors commands: 


e DECLARE CURSOR 
° OPEN CURSOR 

e FETCH 

e CLOSE CURSOR 


After “opening” the cursor, you use it to retrieve multiple rows resulting 
from its associated query. All the rows which satisfy the query’s criteria 
form a set, called the active set of the cursor. Rows of the active set are 
returned, one by one, by “fetching” them. When the query is done, the 
cursor is “closed”. 


The lower limit of the cursor size is determined by the AREASIZE option 
to PCC. In Version 5.0 of ORACLE, cursor size is dynamically allocated 
and can be automatically adjusted. To determine the size needed, see 
“AREASIZE”. 


The DECLARE CURSOR Statement 
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The DECLARE CURSOR statement defines a cursor, by assigning it a 
name and asssociating it with a query, as in the following syntax: 


EXEC SQL DECLARE cursorname CURSOR FOR 
SELECT ... FROM... 


as in: 














EXEC SQL DECLARE C1 CURSOR FOR 
select ename, empno, job, sal 
from emp 
where deptno = :deptno; 


The DECLARE CURSOR statement is a declarative SQL statement. The 
DECLARE CURSOR statement for a cursor must occur before any other 
SQL statement referencing that cursor; Pro*C cannot interpret a reference 
to a cursor not (yet) declared. The scope of a cursor is the entire Pro*C 
program. However, the cursor statements (DECLARE, OPEN, FETCH, 
and CLOSE) must all occur within the same precompiled unit. 


A Pro*C program can declare as many cursors as queries. Every DE- 
CLARE CURSOR statement must be unique; you cannot declare two 
cursors of the same name in one program, even. across blocks or procedures 
of the program. If you will be using many cursors, you may want to use 
the option MAXOPENCURSORS when invoking PCC (see 
“MAXOPENCURSORS’). 


The OPEN CURSOR Statement 


By opening the cursor, the query is evaluated and the active set of rows 
identified. The cursor is opened with the executable SQL statement: 


EXEC SQL OPEN cursorname; 
as in: 
EXEC SQL OPEN C1; 


The input host variables in the WHERE clause, if any, are evaluated, 
thereby identifying which rows satisfy the query (the active set). The cursor 
is placed into an open state and is “placed” just before the first row of the 
active set. However, none of the rows are actually retrieved at this point. 
(This will be done by the FETCH statement.) 


Once you have opened a cursor, its input host variables are not re-examined 
until you re-open the cursor (and therefore the active set will not change). 


Unless you change the actual SQL statement associated with the cursor 
(even if you change the values of the bind variables), the curso’ s SQL 
statement will not be re-parsed by closing and re-opening. However, if you 
change the SQL statement associated with a particular cursor after manip- 
ulating other cursors, the SQL statement associated with the cursor will be 
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reparsed by closing and re-opening the cursor. To change any input host 
variables, and therefore the active set, you must re-open the cursor. 


FETCHing Rows of the Active Set 
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The FETCH statement reads the rows of the active set and names the 
output variables which will contain the results. Remember that the SE- 
LECT statement associated with the query may not include an INTO 
clause; rather, the INTO clause and list of output host variables are in- 
cluded in the FETCH statement. The syntax for the executable SQL 
statement FETCH is: 


EXEC SQL FETCH cursorname INTO :hostvarl, :hostvar2 ... 


as in: 
EXEC SQL FETCH C1 INTO :pename, :pempno, :pjob, :psal; 


The cursor must have been previously declared and opened. The first time 
FETCH is executed, the cursor moves from before the first row in the ac- 
tive set to the first row. This row becomes the current row. Each subse- 
quent execution of FETCH advances the position of the cursor to the next 
row in the active set (changing the current row). The cursor may only 
move forward in the active set. The only way to return to a row which has 
been previously fetched is to close and re-open the cursor, and begin again 
at the first row of the active set. If you close a cursor at row 9000 out of 
10000 rows, you must re-open the cursor and re-fetch. 


Although you may need to execute the fetch statement several times, there 
should only be one set of host variables associated with the FETCH. Ifa 
second FETCH statement with different host variables is issued for an open 
cursor, it is ignored, 


If you wish to change the query, its active set, or any input or output host 
variables, first change the variable, then close and re-open the cursor, and 
execute a FETCH. . 


If the active set is empty, or contains no more rows to be fetched, the 
SQLCODBE is set to + 1403. To perform further operations with a cursor 
which has returned + 1403, you must close and re-open the cursor. 


’ 
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The CLOSE CURSOR Statement 





After you are done fetching rows of an active set, you should CLOSE the 
cursor, to release the resources associated with keeping the cursor open. 
The cursor is closed with the executable SQL, statement: 


EXEC SQL CLOSE cursorname; 


No fetches may be executed against a closed cursor, as its active set be- 
comes undefined. If you execute a fetch against a closed cursor, the error 
indicates an invalid cursor. If you need to re-open a cursor (with different 
values and host variables, for example) simply re-open the cursor. 


The CURRENT OF CURSOR Statement 





Version 1.1 of the ORACLE Programmatic Interfaces supports the SQL 
syntax CURRENT OF CURSOR which is used to refer to the most re- 
cently fetched row of one cursor in an update or delete through another 
cursor. CURRENT OF CURSOR replaces explicit usage of “ROWID” 
in “SELECT FOR UPDATE.” 


EXEC SQL DECLARE EMP_CUR CURSOR FOR 
SELECT ENAME, SAL 
FROM EMP 
WHERE EMPNO = :empno; 
FOR UPDATE OF SAL; 


EXEC SQL OPEN EMP_CUR; 
EXEC SQL FETCH EMP_CUR INTO :ename,:sal; 
EXEC SQL UPDATE EMP 

SET SAL=:new_sal 

WHERE CURRENT OF EMP_CUR; 


CURRENT OF CURSOR can only be used following a fetch. This state- 
ment is equivalent to saving a ROWID and using it. 
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Types of Cursors 
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Though you must explicitly declare cursors for many Pro*C operations, 
Pro*C will automatically create cursors for you for other operations. The 
concept of a cursor applies to Pro*SQL as well as to Pro*C, and some 
clarification of the types of cursors may be useful. 


For every SQL statement that isa DML, DDL, or DCL command, Pro*C 
requires an open Pro*C cursor. Pro*C also requires an ORACLE cursor, 
to access the database. (The number of ORACLE cursors is determined 
by the Pro*C runtime option, MAXOPENCURSORS.) The only time 
you need to explicitly declare cursors is for SELECT statements; for all 
other DML (and DDL and DCL) commands, Pro*C handles all the cursor 
control for you. 


So, the following “types” of cursors exist: 


Explicitly declared cursors Pro*C cursors, logical which are declared in the 
program with the cursor commands and are manipulated to fetch 
query results. For example: 


EXEC SQL DECLARE CURSOR C1... 


Implicitly opened cursors Logical cursors which Pro*C has obtained on 
behalf of the user, with no action by the user. Examples are cur- 
sors Pro*C uses for inserts, updates, single-row selects, etc. 


ORACLE cursors Physical cursors (ORACLE cursors rather than Pro*C 
cursors) which are required for every DML, DDL, or DCL oper- 
ation. They are acquired by Pro*C, with no action by the user. 


The first two cursor types (explicit and implicit) always have a corre- 
sponding ORACLE cursor. As noted previously, MAXOPENCURSORS 
applies to the number of concurrent ORACLE cursors that can be open 
at any one time. If that number is less than the actual number required, 
Pro*C will re-use an existing cursor. However, it will only re-use cursors 
on implicitly opened cursors; explicitly defined cursors are always under the 
user’s program control. 


These distinctions are unnecessary for most users, except those who need 
to work with more complex programs, especially using both Pro*C and 
Pro*SQL. 








a 


SAMPLE PROGRAMS 


The following sample programs illustrate the use of cursors to execute 
queries returning multiple rows. 


Query with a WHERE Clause 


The first example displays all salesmen, and their names, salaries, and 
commissions. 
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/* Example #9 */ 
#include <stdio.h> 


This program is an example of Pro*C which will display al] the 
salesmen in the employee table. It is an example of how to do 
queries that return more than one row. 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[20]; 
VARCHAR pwd[ 20]; 
float sal,comm; 
char ename[ 11]; 
EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


main() 


/* log into ORACLE */ 


strcpy(uid.arr, "SCOTT"); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd.arr, "TIGER"); /* copy the password */ 


pwd. len=strlen(pwd. arr); 


EXEC SQL WHENEVER SQLERROR STOP 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


printf("Connected to ORACLE user: %s \n",uid.arr); 


EXEC SQL DECLARE C1 CURSOR FOR 

SELECT ENAME, SAL, COMM 

FROM EMP WHERE JOB='SALESMAN'; 
EXEC SQL OPEN C1; 


EXEC SQL WHENEVER NOT FOUND STOP 

printf ("SALESMAN NAME\t\tSALARY\t\tCOMMISSTON\n\n"); 

for (33 ) 

{ 
EXEC SQL FETCH C1 INTO :ename,:sal,:comm; 
printf("%-10s\t\t%6.2f\t\t%6.2f \n'"',ename,sal,comm); 


62 / Pro*C User’s Guide 











EXEC SQL CLOSE C1; 


EXEC SQL WHENEVER SQLERROR CONTINUE; /* don't trap errors */ 


EXEC SQL COMMIT WORK RELEASE; 
exit(0); 


/* log off database */ 


Chapter 3. Queries / 63 








A More Complex Query, Using Prompts 


This example prompts for the department number, and then displays the 
names, jobs, and salaries of everyone in the department, ordered by job and 
then by salary. 
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/* Example #10 */ 
#include <stdio.h> 


This program is an example of Pro*C which will display the 
names, jobs and salaries of people in a given department ordered 
by job and by salary. The department number will be prompted for 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
float sal; 
int deptno; 
char job[10]; 
char ename[ 10]; 

EXEC SQL END DECLARE SECTION; 

EXEC SQL INCLUDE SQLCA; 


main() 


/* Jog into ORACLE */ 

strcpy(uid.arr, "SCOTT"); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd.arr, "TIGER" ); 
pwd. len=strlen(pwd.arr); 


/* copy the password */ 


EXEC SQL WHENEVER SQLERROR STOP; 
EXEC SQL CONNECT :uid IDENTIFIED BY :pwd; 


printf("Connected to ORACLE user: %s \n",uid.arr); 


printf("Enter department number: "); 
scanf("%d", &deptno); 


EXEC SQL DECLARE C1 CURSOR FOR 
SELECT ENAME,JOB, SAL 
FROM EMP WHERE DEPTNO=:deptno 
ORDER BY JOB, SAL 

EXEC SQL OPEN C1; 


EXEC SQL WHENEVER NOT FOUND STOP 
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printf("EMPLOYEE NAME\t\tUOB\t\t\tSALARY\n\n"); 
for (33 

EXEC SQL FETCH C1 INTO :ename,:job,:sal; 

printf ("%-1Os\t\t%-LOs\t\t%6.2f \n",ename, job, sal); 


} 

EXEC SQL CLOSE C1; 

EXEC SQL WHENEVER SQLERROR CONTINUE; /* don't trap errors */ 
EXEC SQL COMMIT WORK RELEASE; /* log off database */ 

exit(0); 
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CHAPTER 4. COMMITTING AND ROLLING BACK WORK 








This chapter defines a transaction or logical unit of work, which may group 
several SQL statements together as one unit. The programmer can write a 
program such that he can control when the transactions done by the pro- 
gram are committed (made “permanent”) in the database or rolled back 
(‘erased” from the database). 


In this chapter you'll learn how you can control when changes are made to 
ORACLE data. Because of certain features of ORACLE, all your work is 
not immediately made permanent when you do it; this allows you to make 
sure that every transaction is complete before it is made permanent. In 
other words, no partial transactions are committed. 


ORACLE uses the Before Image file to protect the consistency of the da- 
tabase. The Before Image file stores blocks of the database as they looked 
before a transaction starts. Under certain conditions, these blocks are 
written back to the Database file, undoing the changes that had just been 
made. These conditions can be a result of: 


©  user-initiated ROLLBACK WORK 

o abnormal exit of user process from ORACLE 
o deadlock between processes 

o system failure (hardware or software). 


Abnormal termination of a user process occurs when the process stops 
unexpectedly, due to software or hardware problems, or due to a forced 
interrupt (such as CTRL-T on VAX/VMS systems. Successful termination 
occurs when the user program runs its course, closing cursors, and explictly 
committing or rolling back work, and returning control to the user. 
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LOGICAL UNITS OF WORK 





Starting a Unit of Work 


Ending a Unit of Work 


A logical unit of work is a sequence of SQL statements that ORACLE treats 
as a single entity. All of the SQL statements are treated together; they are 
made permanent at the same time, or they are undone together. For ex- 
ample, a logical unit of work might contain the addition of some money to 
one account (one or more INSERTS) and the subtraction of some money 
from another account (probably INSERTs, though maybe to a different 
table). If both of these transactions are treated in the same unit of work, 
then the database is not in danger of being left in an inconsistent state; ei- 
ther both transactions are made permanent, or neither is. 


A logical unit of work is implicitly begun when the first executable SQL 
statement is encountered (with one exception -- CONNECT). Executable 
statements always occur within a logical unit of work, because any execut- 
able SQL statement, except CONNECT, encountered after one unit of 
work has finished automatically starts another unit of work. Only execut- 
able SQL statements are included in units of work; declarative statements, 
though they may occur during a logical unit of work, have no effect on it. 
They do not start a logical unit of work, nor must they occur within one. 
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As mentioned above, the end of a unit of work may be user- or system- 
initiated. A user (or application program) can explicitly write (COMMIT) 
his changes to the database, or he can undo them (ROLLBACK), Occa- 
sionally, two ORACLE users will contend for the same resources and nei- 
ther can finish until the other releases some resource. This is called a 
deadlock, and ORACLE detects it and undoes the work of one user, based 
on certain criteria. If there is a hardware or software failure, ORACLE 
undoes all transactions active at the time of the failure, so none of them 
leaves the database in an inconsistent state. 


Several SQL statements perform an automatic commit with their successful 
execution. See “COMMIT WORK”. 











Resources Required by a Unit of Work 


COMMIT WORK 





If in the course of a SOL statement a program obtains locks, those locks 
can only be released by committing, closing the cursor, or logging out. 
When using SELECT ... FOR UPDATE, row level locks acquired do not 
get released until either a commit is issued or one of the other two actions 
is taken. 





The COMMIT WORK statement ends the current logical unit of work, if 
one is in progress, and makes permanent any changes made during that unit 
of work. The syntax follows: 


EXEC SQL COMMIT WORK [RELEASE] 


The optional parameter, RELEASE, returns all resources (including 
ORACLE cursors) owned by the program and logs pou off the database. 


You should always explicitly commit or rollback the last unit of work in a 
program using the RELEASE option, Though ORACLE will automatically 
commit pending changes upon successful termination of a program, it will 
rollback changes if the program terminates abnormally. 


‘The COMMIT WORK statement has no effect on the contents of the host 
variables or on the control flow of the program. 


Every DDL statement (statements which CREATE or DROP database 
objects, such as tables, indexes, or views) issues an automatic COMMIT 
WORK. Therefore, COMMITs need not be coded for DDL statements. 


Note that the logical unit of work in progress when the DDL is executed 


is committed before the DDL is executed; thus, whether or not the DDL 
succeeds, the prior transaction is committed. 
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ROLLBACK WORK 





The ROLLBACK WORK statement ends the current logical unit of work, 
if one is in progress, and undoes any changes made during that unit of 
work. The syntax follows: 


EXEC SQL ROLLBACK WORK [RELEASE] 


The optional parameter, RELEASE, returns all resources (including 
ORACLE cursors) owned by the program and logs pou off the database. 


You should always explicitly commit or rollback the last unit of work in a 
program using the RELEASE option. Though ORACLE will automatically 
commit pending changes upon successful termination of a program, it will 
rollback changes if the program terminates abnormally. 


The ROLLBACK WORK statement has no effect on the contents of the 
host variables or on the control flow of the program. 


If you use ROLLBACK WORK in a routine which is entered on an error 
or warning, and you also use a WHENEVER statement, a program loop 
is possible if ROLLBACK fails with an error or warning. You can avoid 
this by specifying WHENEVER SQLERROR CONTINUE and WHEN- 
EVER SQLWARN CONTINUE before the ROLLBACK WORK state- 
ment. 


THE RELEASE OPTION 
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The preceding sections both note that the last occurrence of COMMIT 
WORK or ROLLBACK WORK in a program should use the option 
RELEASE. If RELEASE is not specified, then locks obtained during the 
program will be held after program termination until CLN recognizes that 
the process is no longer active. This will cause other users in a multi-user 
environment to wait for or fail to obtain the locked resources. 





CHAPTER 5. ERROR DETECTION AND RECOVERY 








In this chapter you'll learn how to use the SQLCA and indicator variables, 
to detect and act on different conditions, such as null values, non- 
conditional deletes, no row returned, and data overflow or truncation. 


USING RETURNED VALUES IN INDICATOR VARIABLES 


As noted earlier, every host variable may have an optional variable associ- 
ated with it: an indicator variable Indicator variables are used to see whether 
a particular field’s value 


e was placed into the host variable without truncation or being NULL 


e is NULL 


o has been truncated because the returned value is wider than the de- 
clared. width for the corresponding host variable. 


Figure 5 on page 72 shows the possible values an indicator variable may 
return. 
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Value Meaning 





0 The returned value has been placed into 
the host variable. It is not null and 
has not been truncated. 


-1 The returned value is NULL. The value 
of the main variable is undefined. 


>0 The returned value was truncated. The 
width of the main variable was not 
sufficient. The actual value of the 
indicator variable is the width 
before truncation 





Figure 5. Possible Indicator Variable Values 


Using Indicator Variables and NULLS 


To Search for NULL Values 


To Insert NULL Values 
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The primary reason for using indicator variables is to manipulate NULL 
values; the following sections give some examples. 


(See “Indicator Variables” for more general information on indicator vari- 
ables.) 


Note that you cannot use indicator variables for search conditions (in the 
WHERE clause). For example: 


SELECT ... WHERE COMM = :PCOMM: PCOMMI 
is invalid and will return a negative sqlca.sqlcode. The correct syntax is: 


SELECT ... WHERE COMM IS NULL 


Indicator variables can be used to insert NULL values. First, in the DE- 
CLARE section, define a 2-byte integer variable (in C, a short variable). 
Then, before the insert, set the indicator variable(s) for the column(s) you 
want to be NULL, to be -1, as shown in the following example: 
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ename = "clair"; | 
:icomm = ~1; i 
EXEC SQL insert into emp (ename, comm) | 
values (:ename, :comm:icomm); | 


which is a better programming alternative than: 


ename = "clair" 
EXEC SQL insert into emp (ename, comm) 
values (:ename, null); | 





because the NULL is hardcoded in the second case. In the first case, the 
indicator variable is pre-set to -1 (NULL) so the value of the host variable 
is undefined. 


To Output NULL Values 
The following code excerpt would allow a programmer to spot null values 
and control their appearance. Note that all output host variables are as- 
sumed to be characters except icomm. 


EXEC SQL select ename, sal, comm 
into :ename, :sal, :comm:icomm 


from emp 
where empno = :empno; 
if (icomm == -1) 
comm = "na/" 
printf(... 
THE SQLCA STRUCTURE 





The SQLCA is a structure used by every Pro*C program to pass informa- 
tion about the execution of the program. For example, it will point out if 
there are not enough variables in a SQL statement to return the requested 
data, so a programmer can correct the SQL statement. It will also indicate, 
for particular transactions, whether null values were ignored, or whether the 
data has changed since the query started, so a programmer can anticipate 
particular data conditions. 


In the ORACLE distribution directory you will find a sample SQLCA 
(look for the file named SQLCA, with the same extension as C source files 
on your system). You can always use EXEC SQL INCLUDE SQLCA to 
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include files when necessary. You do not need to specify the filename ex- 
tension. 


The scope of a SQLCA is limited by the restrictions of the host language. 
In C you may wish to use one global SQLCA and/or several local ones. 
Access to local SQLCAs is limited by their scope within the language. 


If a program uses only one SQLCA, then it is recommended that the pro- 
grammer copy out of the SQLCA any information that he wishes to save 
or refer to before the next SQL statement is executed. (In particular, he 
might want to copy sqica.sqlcode and the elements of sqlca.sqlwarn.) 


It is permissible to code the SQLCA directly in the program rather than 
using the INCLUDE SQLCA statement. If you do so, you can specify any 
name for the structure. 


You can use multiple SQLCAs in your program -- for example, to save 
information returned by a transaction (such as ROW NOT FOUND), you 
might use two SQLCAs, in two different routines, each as a “local variable”. 
Note that at any one time only one SQLCA is used by Pro*C to store or 
return information. 


When to Refer to the SQLCA 
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The SQLCA is updated after the execution of every executable SQL state- 
ment; the meaning of the SQLCA is undefined after a declarative statement. 
Cautious programmers will check the SQLCA, therefore, after every non- 
declarative statement. In particular, you should check the SQLCA after 
every DML statement, because INSERT and UPDATE statements may 
fail after processing some rows of a table, in which case you probably ought 
to issue a ROLLBACK WORK command to restore the database to a 
consistent state. 


With the SQL statement WHENEVER, you can detect abnormal condi- 
tions and specify appropriate actions based on the condition. Because the 
default WHENEVER statement is: 


EXEC SQL WHENEVER anyerror CONTINUE; 


Pro*C will attempt to continue processing regardless of errors 
encountered. It is recommended that you use the WHENEVER statement 
to trap errors and take action at the point they are detected. 


See “The WHENEVER Statement” for a description of the WHENEVER 
statement and options. 

















The Meaning of SQLCA’s Individual Elements 


The structure of the SQLCA in Pro*C is shown in Figure 6. 





struct sqica f 


p 


char sqicaid[8]; 
long sqicabc; 
long sqicode; 
struct { 
unsigned short 
char 
} sqlerrm; 
char sqlerrp[8]; 
long sqlerrd[6]; 
char sqlwarn[ 8]; 


char sqlext[8]; 


struct sqlica sqlca; 


Figure 6. 


sqlerrm]; 
sqlerrmc[ 70]; 








The Structure of the SQLCA 


The individual fields of the SQLCA are described below. Note that the first 
two fields (sqica.sqlcaid and sqlca.sqlcabc) are relevant primarily for 
FORTRAN, not for C. 


sqlca.sqicaid A character string. This field is initialized to "SQLCA” when 


allocated, but only if it is used as a global structure. 


sqlea.sqicabe A 4-byte binary integer. This field is set to the length, in 


bytes, of the SQLCA structure itself. 


sqica.sqlcode A 4-byte binary integer which summarizes the results of exe- 


cuting a SQL statement. 


indicates successful execution. 


positive indicates successful execution, with a status code, Cur- 
rently the only positive code is 1403, “no row found” or 
last row returned. 


negative indicates an error in the program, or system failure. 
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If a fatal error occurs, the program should not be allowed to 
continue. The possible errors are listed in the guide ORACLE 
Error Messages and Codes. 


sqlca.sqlerroi.sqlerrm) Contains the length of the text 
(sqica.sqlerrm.sqlerrmc). 


sqlea.sqlerrm.sqlerrme A character string of varying length, which is the er- 
ror text corresponding to the error number found in sqlca.sqlcode. 


sqlca.errp Currently unused, this field is a character string. 


sqlea.sqlerrd This is an array of six 4-byte binary integers used to describe 
the internal state of the ORACLE RDBMS. {Only the third ele- 
ment [2] is currently used; it indicates the number of rows proc- 
essed for DML operations such as INSERT or UPDATE. 
Elements 0,1,3,4 and 5 are currently unused. i 


sqlca.sqlwarn A sub-structure composed of eight single-character elements. 
These elements act as warnings for different conditions which may 
occur during precompilation. For example, a warning is set when 
ORACLE ignores null values in computing an average. Ifa 
warning is set, the element’s valuc is set to °W’; otherwise the el- 
ement’s value is a blank. If one or more warnings are set, the first 
element, sqlca.sqwarn[0], is also set to “W’. 


Descriptions of each of the elements in sqlca.sqlwarn follow. 
Note that the eight elements are identified as elements [0] through 


vi. 


sqica.sqlwarn|[0] If sqlca.sqlwarn[0] is a blank, then no warnings were set for 
the particular statement. If sqlca.sqlwarn[0] is set to W’, then 
one or more warnings were set and should be checked. Not every 
W” signifies a grievous error, but each warning will alert a pro- 
grammer to certain problems or conditions which he may want 
to check. 


sqica.sqlwarn|1] If the second element, sqlca.sqlwarn[1], is set to ‘W’, then 
one or more returned character fields was truncated because the 
host variable’s declared width was insufficient. This applies only 
to character data; ORACLE truncates certain numeric data with- 
out setting a warning or returning a negative sqlca.sqlcode. 


To determine which fields were truncated and by how much, you 
must refer to the indicator variables for the returned data. If an 
indicator variable is positive, its value is the length of the data 
before trancation (and the host variable’s width should be in- 
creased accordingly). 

















sqlca.sqiwarn[2] The third element of sqlca.sqlwarn points out a condition, 
which, though not necessarily an error, may be useful to the pro- 
grammer. 


If set to ‘W’, sqlca.sqlwarn[2] indicates that one or more null val- 
ues was ignored in the computation of a function, such as AVG, 
SUM, MIN, or MAX. If appropriate, the programmer may want 
to use the Null Value function (NVL) to temporarily assign values 
for the null data (such as temporarily assigning all null values to 
be zero). 


sqlca.sqlwarn[3] If the fourth element, sqlca.sqlwarn(3}], is set to W’, it in- 
dicates that the number of items in the SELECT list does not 
equal the number of host variables in the INTO clause. Though 
data is returned, the number of items returned is the lower of the 
two. 


sqica.sqlwarn|4] If the fifth element, sqlca.sqlwarn([4], is set to “W’, then ei- 
ther an UPDATE or a DELETE statement has been coded 
without a WHERE clause, signifying that every row in the table 
will be updated or deleted (sometimes called an “unconditional 
UPDATE or DELETE’, because no WHERE clause is used to 
restrict which rows are updated or deleted). As it is more com- 
mon to update or delete one row or groups of rows, ORACLE 
sets the warning so that unconditional updates or deletes can be 
noted and either confirmed or rolled back. 


sqica.sqlwarn[5| The sixth element, sqlca.sqlwarn|5], is currently unused. 


sqica.sqtwarn[6] The seventh element, sqlca.sqlwarn[6], is set to °W” if the 
SQL statement just executed caused ORACLE to roll back a 
logical unit of work. Note that this clement is not set after a 
ROLLBACK WORK statement -- rather it is set when the 
ROLLBACK WORK was implicit. For example, 
sqlca.sqlwarn|6] is set to “W” when a transaction is rolled back due 
to a deadlock. 


sqlca.sqlwarn[7] The eighth element, sqlca.sqlwarn[7], is set to “W’ ifa row’s 
current data differs from the query-consistent data (or was deleted 
subsequent to the query’s start). It is set on return from a fetch, 
if a column appearing in the query and belonging to a table ap- 
pearing in a FOR UPDATE clause has changed between the time 
the query started and when the row was fetched and locked. For 
this warning to be set, the column /nust appear in the query’s 
SELECT list and the column must be in a table named in the 
FOR UPDATE clause. 
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This element is not compatible with SOL|DS nor DB2, which do 
not have this feature. Users wishing to maintain compatibility with 
those systems should not use this element. 


sqica.sqlext The last field of the SQLCA, sqica.sqlext is currently unused. 
(It is intended to return a character string). 


THE WHENEVER STATEMENT 





The WHENEVER statement is an optional declarative statement, which 
when used, determines what actions will be taken upon detection of an er- 
ror. Your program can contain direct references to the parts of the 
SQLCA, or it can use WHENEVER statements. The use of WHENEVER 
statements is generally both easier and preferred, because WHENEVERs 
can check where explicit checking cannot (see "WHENEVER versus Ex- 
plicit Error Checking’). 


WHENEVER detects errors by checking the SQLCA after every executable 
SQL statement. WHENEVER can be used to detect ORACLE errors 
(those listed in the ORACLE Error Messages and Codes Manual), Pro*C 
warnings (such as truncation of a field or the use of NULL in a function), 
and end of fetch conditions. 


Syntax for the WHENEVER Statement 





The syntax for WHENEVER is shown in Figure 7. 





EXEC SQL WHENEVER [ SQLERROR SQLWARNING NOT FOUND Jj 


L STOP CONTINUE GO TO stmt-label J; 


Figure 7. Syntax for the WHENEVER Statement 


where: 

SQLERROR is set when sqlca.sqlcode is negative. 

SQLWARNING is set when sqica.warn(0] is set to “W7? 

NOT FOUND is set when sqica.sqicode is + 1403 (“no row found’), 
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STOP causes program termination. The logical unit of work is rolled 
back. 


CONTINUE ignores the sqlca condition and causes the next sequential 
program instruction to be executed. 


GO TO (or GOTO) causes control to pass to the statement at the specified 
label. The label cannot exceed 18 characters. 


By default, a Pro*C program will CONTINUE when it encounters any of 
the three conditions: a negative sqica.sqicode, sqlca.sqlwarn{0] set to OW 
or a sqica.sqleode of 1403. 


Change in Behavior of NOT FOUND 





Beginning with Version 1.0.5, the behavior of NOT FOUND is compatible 
with IBM’s product DB2. That is, NOT FOUND is set for both: 


EXEC SQL DELETE EMP EXEC SQL UPDATE EMP 
WHERE ... SET 
WHERE ... 


when no rows satisfy the WHERE clause. ‘The error message has been re- 
worded to make it more meaningful, from “END OF FETCH’ to “NO 
DATA FOUND”. 

WARNING: This new NOT FOUND processing means that some pro- 
grams which were not careful about handling WHENEVER NOT FOUND 
will fail. For example, the following will fail by going into an infinite loop, 
if the WHERE clause on the DELETE statement causes NOT FOUND 
to be set: 


EXEC SQL WHENEVER NOT FOUND GO TO 200 
100 CONTINUE 

EXEC SQL FETCH C INTO 

GO TO 100 


200 CONTINUE 
EXEC SQL DELETE EMP WHERE 
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Scope of the WHENEVER Statement 


Because the WHENEVER statement is a declarative statement, its scope 
is determined by its physical position in the code, not by its placement in 
the flow of logic. The precompiler generates the code in a single pass 
through the source program. 


WHENEVER versus Explicit Error Checking 
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You can code explicit checks on the SQLCA to see if error codes or 
warnings have been set. You can do this in addition to using WHEN- 
EVER statements or instead of using them. 


The use of one of the options CONTINUE or GOTO is recommended 
with WHENEVER statements, rather than STOP. Though STOP is a 
valid option, using it means that the program will simply terminate -- no 
final reporting, totalling, summarizing or other feedback is given. The 
WHENEVER statement should precede the executable SQL statements 
you wish to test. For example, see Figure 8 on page 81. 














EXEC SQL WHENEVER SQLERROR GOTO labx; 


labx: printf ("Program terminated. SQLCODE is: %d/n" , sqicode); 
EXEC SQL WHENEVER SQLERROR CONTINUE; 
EXEC SQL ROLLBACK WORK RELEASE; 
exit(1); 





Figure 8. Using WHENEVER and an Explicit Error Checking Routine 


In Figure 8, control goes to “labx” if a SQLERROR condition occurs. 
Then the program displays the sqlcode (a negative number indicating an 
ORACLE error), rolls back the logical unit of work, and terminates the 
program. The WHENEVER SQLERROR CONTINUE statement is 
used to prevent a program loop resulting from ROLLBACK WORK 


producing an error. 


Explicit error checking is done after every ORACLE call, whether you use 
a WHENEVER statement or directly code checks against the SQLCA. 


SAMPLE PROGRAMS 


The following program executes the query: 
SELECT * FROM EMP 


and demonstrates some error checking. 
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/* Example #11 */ 
#include <stdio.h> 


This program is an example of Pro*C which uses error checking. 

Columns from the employee table will be displayed and if any 

errors are encountered appropriate action will be taken. 
BESS SS SS SS me Re / 
EXEC SQL BEGIN DECLARE SECTION; 

VARCHAR uid[ 20]; 

VARCHAR pwd[ 20]; 

int empno; 

char ename[ 10]; 

char job[10]; 

int mgr; 

char hiredate[9]; 

float sal; 

float comm; 

int deptno; 

short empnoi,enamei, jobi,mgri,hiredatei,sali,commi,deptnoi; 
EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


main() 
/* log into ORACLE */ 
strcpy(uid.arr, "SCOTT"); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd. arr, "TIGER"); /* copy the password */ 


pwd, len=strlen( pwd. arr); 


EXEC SQL WHENEVER SQLERROR GOTO errprt; 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


printf("Connected to ORACLE user: %s \n",uid.arr); 

EXEC SQL DECLARE C1 CURSOR FOR 
SELECT EMPNO, ENAME,JOB,MGR,HIREDATE, SAL, COMM, DEPTNO 
FROM EMP; 

EXEC SQL OPEN C1; 


printf("EMPNO EMPLOYEE JOB MGR\n"); 
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printf(" HIREDATE SAL COMM DEPTNO\n"); 
EXEC SQL WHENEVER NOT FOUND GOTO finish; 


for (33 } 
EXEC SOL FETCH C1 INTO :empno:empnoi,:ename:enamei, : job :jobi, 
imgrimgri, :hiredate:hiredatei,:sal:sali, 
:comm: commi , :deptno:deptnot; 
if (empnoi) empno = ~1; /* null found */ 
if (enamei) ename = ""; /* null found */ 
if (jobi) job = ""; /* null found */ 
if (mgri) mgr = ~1; /* null found */ 
if (hiredatei) hiredate = ""; /* null found */ 
if (sali) sal = ~l; /* null found */ 
if (commi) comm = -1; /* null found */ 
if (deptnoi) deptno = ~1; /* null found */ 
printf("%5d %-10s %-9s %5d \n", 
empno,ename, job,mgr); 
printf(" 29s %6.2f %6.2f %5d\n", 
hiredate, sal,comm,deptno); 
} 
finish: 


printf("\n select completed. \n"); 

EXEC SQL CLOSE C1; 

EXEC SQL WHENEVER SQLERROR CONTINUE; 

EXEC SQL COMMIT WORK RELEASE; /* log off database */ 
exit(0); 

errprt: 


printf("\n %, 70s \n", sqica. sqlerrm. sqlerrmc); 

EXEC SQL ROLLBACK WORK RELEASE; /* log off database */ 
exit(1); 

} 
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CHAPTER 6. DYNAMICALLY DEFINED STATEMENTS 











This chapter covers advanced programming techniques, which are useful for 
writing extremely flexible programs but require greater understanding of the 
programmer about coding in C and the SQL language. 


Beginning Pro*C users should either skip or skim this chapter. 


Most application programs are designed with specific uses in mind: for 
example, changing employee data by entering an employee's full name, or 
entering a date and transactions made on that date. In these cases, the na- 
ture, or “structure”, of the transaction can be predetermined to a great ex- 
tent; that is, the programmer knows which tables may be changed, which 
fields are necessary for inserts or updates, and what their datatypes and 
constraints are. 


However, some applications may prefer to be able to accept and process 
many sorts of SQL statements, regardless of whether they are simple DE- 
LETES or UPDATES or more complex queries. In these cases, a pro- 
grammer wants to be able to let the program accept any valid SQL 
statement entered at runtime, and process it. It is very possible that neither 
the SQL statement nor its structure will be known by the program. For 
example, a simpler Pro*C program might prompt the user for the employee 
numbers for records needing to be updated. A Pro*C program which in- 
cludes a dynamically defined SQL statement might simply prompt for a 
SQL statement, be it an INSERT, CREATE, SELECT, or whatever, and. 
after some checking, complete the transaction. Thus, dynamically defined 
statements give programmers and end-users much more flexibility in what 
their programs can accomplish. 


Dynamic SQL also can be used to construct a SOL statement from a text 
string entered by the user. Using this form of dynamic SQL does not re- 
quire the user to know SQL, but still allows the exact structure of the SQL 
statement to be unknown until runtime. 
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DEFINITION OF DYNAMICALLY DEFINED STATEMENTS 


Dynamically defined statements are SQL statements which are not known 
at compile time; the statement can, and probably will, change from exe- 
cution to execution. 


As when coding “static” SQL statements into Pro*C programs, SQL SE- 
LECT STATEMENTS -- especially those returning more than one row 
-- are somewhat more complex to code than SQL statements which simply 
“return” success or failure. 


TYPES OF DYNAMICALLY DEFINED STATEMENTS 
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This chapter addresses four ways to program dynamic statements into your 
program. The four methods are summarized in Figure 9 on page 87. 











Method 1: Using the EXECUTE IMMEDIATE Statement 
Precompiles any SQL statement (except a SELECT) and executes it. 
The SQL statement can be a literal or a host variable. 

It may not contain any host variables (neither input 
nor output host variables). 


Method 2: Using the PREPARE and EXECUTE Statements 
Takes any SQL statement (except SELECTS) and executes it. 
The statement can contain input or output host variables. Though 
it can be reused for “any” SQL statement, both the number of 
variables and the corresponding datatypes must always be the same. 


Method 3: Using the PREPARE and FETCH Statements 
Allows use of selects. The statement may contain input 
or output host variables. The sequence for this method is: 
PREPARE, DECLARE, OPEN, FETCH. 
The number of variables and their corresponding datatypes must 
always match. 


Method 4: Using Bind and Define Descriptors 
Allows the use of any SQL statement, including single and multi-row 


SELECTs. 








Figure 9. Methods of Programming Dynamic SQL Statements 


While the first three methods are simpler conceptually, they impose some 
constraints upon the programmer and user. The fourth method allows the 
most flexibility, but requires a greater understanding of ORACLE concepts 
on the part of the programmer. 


The simplest cases of dynamically defined statements are when the SQL 
statement returns no values except “success” or “failure”. This includes all 
DDL and DCL statements, and all DML commands except SELECTs. 
Examples of these commands are: 


CREATE TABLE 

DROP INDEX 

UPDATE table SET column = value 
GRANT SELECT ON table TO username 
REVOKE CONNECT FROM username 


In each case, the only result is the set of values in the SQLCA, which sim- 
ply indicates whether the operation succeeded or failed. 
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Coding dynamic SELECT statements is more complex, because the “shape” 
of the result (number of columns returned, their datatypes, and maximum 
widths) is not known in advance. with each DDL statement. 


ACCEPTING INPUT FOR DYNAMIC SQL STATEMENTS 


Pro*C requires the following for a statement entered as a dynamic SQL 
statement: 


o Jt must not contain any host language delimiters. 
o It must not be prefixed by EXEC SQL. 
o Jt may contain host language variables, 


For example, the following is not valid: 
s = "EXEC SQL DELETE..."; 
EXEC SQL EXECUTE IMMEDIATE :s; 


because the assignment of the variable s includes the host language delim- 
iters “EXEC SQL”. 


A variable containing a SQL statement entered dynamically during a Pro*C 
program may contain parameters, as in: 


DELETE FROM EMP WHERE EMPNO = :PEMPNO 


If a dynamic statement contains no parameters and is not a query, then the 
EXECUTE IMMEDIATE statement will precompile and run it (see 
“Method 1: EXECUTE IMMEDIATE’). If a dynamic statement contains 
parameters, it requires the use of the two statements: PREPARE, and 
EXECUTE (see “Method 2: PREPARE and EXECUTE’). 
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Notes on Using DDL Statements 


Version 1.0 of the ORACLE Programmatic Interfaces flushes the cursor 
cache with every execution of a DDL statement (such as CREATE TA- 
BLE). This has the following results: 


e Programs which use temporary tables (by doing a CREATE, IN- 
SERT, and DROP in fairly rapid succession) can now successfully 
DROP the table, whereas in Version 4 ORACLE they would see the 
following message: 


DDL operation and resource not available 


because a parse lock would still be held on the table. 


o Jf you intermix DDL statements with DML statements, you may no- 
tice some performance degradation due to the flushing of the cursor 
cache. 


METHOD 1: EXECUTE IMMEDIATE 


To read, precompile, and execute a statement you can use the SQL exe- 
cutable statement EXECUTE IMMEDIATE, followed by either a literal 
or variable containing the SQL statement to be executed. For example, see 
the following examples of EXECUTE IMMEDIATE: 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR dstring [80]; 


EXEC SQL END DECLARE SECTION; 
if scanf("%s",dstring); 


EXEC SQL EXECUTE IMMEDIATE :dstring; 


Note that DSTRING is any host variable; it is not a keyword, Alterna- 
tively, you can use character string literals: 


EXEC SQL EXECUTE IMMEDIATE "DELETE FROM EMP WHERE EMPNO = 9251"; 


Alternatively, you could code the DELETE statement directly into the 
program: 
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scanf("%d", &PEMPNO); 
while (PEMPNO != 0) 


{ 
EXEC SQL DELETE FROM EMP WHERE EMPNO = : PEMPNO; 
scanf("%d", &PEMPNO); 


in which case, the DELETE statement will be executed repeatedly until an 
PEMPNO of 0 is entered. 


Prerequisites for EXECUTE IMMEDIATE 





To use EXECUTE IMMEDIATE the following must be true: 
o The SQL statement cannot be a query. 


e The SQL statement cannot contain a host variable. 


Limitations of EXECUTE IMMEDIATE 


The EXECUTE IMMEDIATE statement can be executed only once with 
a single parameter. 
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Example of EXECUTE IMMEDIATE 





/* Example #12 */ 
#include <stdio.h> 


This program is an example of Pro*C which will prompt for a 
WHERE clause to be used in an update statement. This is to be 
used with EXECUTE IMMEDIATE. 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[ 20]; 
VARCHAR pwd 20]; 
char select[132]; 

EXEC SQL END DECLARE SECTION; 

EXEC SQL INCLUDE SQLCA; 


main() 


char where[ 80]; 
int scode; 


/* log into ORACLE */ 

strcpy(uid.arr,"SCOTT"); /* copy the user name */ 
uid. len=strlen(uid. arr); 

strcpy(pwd. arr," TIGER"); /* copy the password */ 
pwd. len=strlen(pwd. arr); 


EXEC SQL WHENEVER SQLERROR STOP; 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


printf("Connected to ORACLE user: %s \n",uid.arr); 
strcpy(select,"UPDATE EMP SET COMM = 100 WHERE "); 
printf("Please enter where clause for the following: \n"); 


printf("%s", select); 
scode = scanf("%s", where); 
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if (scode == EOF !! scode == 0) 

{ 
printf("Invalid entry. \n"); 
exit(1); 


strcat(select, where); 

EXEC SQL EXECUTE IMMEDIATE : select; 

printf("%d records updated. \n",sqica.sqlerrd[2]); 

EXEC SQL WHENEVER SQLERROR CONTINUE; /* don't trap errors */ 


EXEC SQL COMMIT WORK RELEASE; /* log off database */ 
exit(0); 


METHOD 2: USING PREPARE AND EXECUTE 





The two statements PREPARE and EXECUTE are like an EXECUTE 
IMMEDIATE done in two steps. The advantage to PREPARE and EX- 
BCUTE is that the SQL statement is parsed (PREPARED) only once, but 
may be executed numerous times. Thus, with PREPARE and EXECUTE 
the SQL statement can contain a host variable, whereas with EXECUTE 
IMMEDIATE the SQL statement cannot. 


Consider again the example SQL statement which contains an input host 
variable, PEMPNO: 


DELETE FROM EMP WHERE EMPNO = :PEMPNO 
The PREPARE statement does two things: it parses (precompiles) the SQL 
statement, and it gives a statement name to the SQL statement. (Note that 


this name is not a host variable, just as a cursor name is not.) However, 
statement must be declared as a host variable. 


scanf("%s", &DSTRING) 
EXEC SQL PREPARE S1 FROM :DSTRING; 


The EXECUTE statement executes the statement just precompiled, using 
the values supplied for each parameter (the example uses just one parame- 
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ter, PEMPNO). To use more than one parameter, use the format USING 
‘VARI, :VAR2,... 


scanf("%d", &PEMPNO) 
while (PEMPNO !=0) 


{ 
EXEC SQL EXECUTE S1 USING :PEMPNO; 
scanf("%d", &PEMPNO); 


} 


The SQL statement is PREPAREd just once, but it is EXECUTEd as of- 
ten as desired, within the same logical unit of work. If the current trans- 
action is committed or rolled back, and the SQL statement is to be 
re-EXECUTEA, the statement must be PREPAREG again. 


Limitations to PREPARE and EXECUTE 


To use PREPARE and EXECUTE, the number of parameters and their 
datatypes must be known, as the input host variables must be declared in 
the DECLARE section. In the previous example, only SQL statements 
using one variable, which is known to be integer, can be successfully en- 
tered. The SQL statement cannot be a query. For example, all of the fol- 
lowing could be successfully executed: 


INSERT INTO DEPT (DEPTNO) VALUES (:DEPTNO); 
UPDATE DEPT SET ENAME = 'SALES' WHERE DEPTNO = :DEPTNO; 
UPDATE DEPTNO SET LOC = :LOC; 
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Example of PREPARE and EXECUTE 


The example that follows demonstrates the use of PREPARE and EXE- 
CUTE. 
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/* Example #13 */ 
#include <stdio.h> 


This program is an example of Pro*C which will prompt for a 

WHERE clause to be used in an update statement. The UPDATE statement 
includes a bind variable for COMM. This example uses PREPARE and 
EXECUTE. 


EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
float comm; 
char select[132]; 

EXEC SQL END DECLARE SECTION; 

EXEC SQL INCLUDE SQLCA; 


main() 


char where[80]; 
int scode; 


/* log into ORACLE */ 


strcpy(uid.arr, "SCOTT" ); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd.arr, "TIGER" ); /* copy the password */ 


pwd. len=strlen(pwd.arr); 


EXEC SQL WHENEVER SQLERROR GOTO errrpt; 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


printf("Connected to ORACLE user: %s \n",uid.arr); 


strcpy(select,"UPDATE EMP SET COMM=:comm WHERE "); 
printf("Please enter where clause for the following: \n"); 
printf("%s", select); 
scode = scanf("%s", where); 
if (scode == EOF !! scode == 0) 
{ 

printf("Invalid entry. \n"); 

exit(1); 
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strcat(select, where); 

EXEC SQL PREPARE S1 FROM : select; 
printf("Please enter commission:  "); 
scanf("%f", &comm); 

EXEC SQL EXECUTE S1 USING : comm; 


printf("\n %d records updated. \n",sqica. sqlerrd[2]); 
EXEC SQL WHENEVER SQLERROR CONTINUE; /* don't trap errors */ 





EXEC SQL COMMIT WORK RELEASE; /* log off database */ 
exit(0); 

errrpt: 
printf("\n %.70s \n",sqlca.sqlerrm. sqlerrmc); 
EXEC SQL ROLLBACK WORK RELEASE; /* log off database */ 
exit(1); 

} 


METHOD 3: PREPARE, OPEN, AND FETCH 





Method 3 is similar to using PREPARE and EXECUTE, but allows the 
highly desirable flexibility of using queries. If the SQL statement to be ex- 
ecuted is a query, then you must use either Method 3 or 4. Method 3 al- 
lows the use of pre-programmed, or non-dynamic, queries -- that is, queries 
whose SELECT list is known and can therefore be programmed, but whose 
search criteria (as in the WHERE clause) or ordering (the ORDER BY 
clause) may vary. 


Method 3 involves five steps: 
PREPARE <statement name>FROM <host character string> 


DECLARE <cursor name> FOR <statement-name> 
OPEN <cursor name> [USING :bnd-varl [,:bnd-var2,..]] 


FETCH <cursor name> INTO :select-varl [, select-var2,... 


CLOSE <cursor name> 


With this method, first the SQL statement is PREPAREd and then a cur- 
sor is associated with it (DECLAREd), the SQL statement is parsed, and 
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active rows identified. After these steps, the FETCH statements begin to 
fetch subsequent rows of the active set. 


You can optionally use the USING clause in this method. For example, 


EXEC SQL PREPARE S FROM :SEL; (where 
SEL = "SELECT ename 
from emp 
where sal > = 
ra and sal < = :b 
and mgr 3% 
(:c, :d, :e)® 


Note that the names in the USING clause are the real host variable names 


and need not match what is in the PREPARE statement. In fact, a through 
e do not need to be host variables because they are simply place holders. 


Example showing PREPARE, DECLARE, OPEN, FETCH 





The following example prompts for a WHERE clause to be used in a select 
statement. 
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/* Example #14 */ 
#include <stdio.h> 


This program is an example of Pro*C which will prompt for a 
WHERE clause to be used in a select statement. 
This example uses PREPARE,DECLARE,OPEN & FETCH since this may be 
a multi-row select and would require a cursor. 
EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
int deptno; 
char ename[ 10]; 
float sal; 
char select[132]; 
EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


main() 


char where[80]; 
int scode; 
int is /* Joop counter */ 


/* log into ORACLE */ 

strepy(uid. arr, "SCOTT"); /* copy the user name */ 
uid. len=strlen(uid. arr); 

strcpy(pwd.arr, "TIGER" ); /* copy the password */ 
pwd. len=strTen(pwd. arr); 


EXEC SQL WHENEVER SQLERROR GOTO errrpt; 
EXEC SQL CONNECT :uid IDENTIFIED BY :pwd; 


printf("Connected to ORACLE user: %s \n",uid.arr); 


strcpy(select, "SELECT ENAME,SAL FROM EMP "); 
printf("Please enter where clause for the following: \n"); 
printf("%s", select); 

scode = scanf("%["\n]", where); 

if (scode == EOF !! scode == 0) 

{ 
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endloop: 


errrpt: 





printf("Invalid entry. \n"); 
exit(1); 


strcat(select,where); 


EXEC SQL PREPARE S1 FROM :select; 
EXEC SQL DECLARE C1 CURSOR FOR $1; 
EXEC SQL OPEN C1; 

print f( "Employee \tSalary Nee 
printf ("---------- \tose-sas-= \n"); 


EXEC SQL WHENEVER NOT FOUND GOTO endloop; 
for (i=0; ; i++) 


EXEC SQL FETCH C1 INTO :ename,:sal; 
printf("%10s\t%6.2f\n", ename, sal); 


printf("\n\n%d records selected. \n", i); 
EXEC SQL WHENEVER SQLERROR CONTINUE; 
EXEC SQL COMMIT WORK RELEASE; 

exit(0); 


/* log off database */ 


printf("\n %.70s \n",sqlca.sqlerrm. sqlerrmc); 
EXEC SQL ROLLBACK WORK RELEASE; 
exit(1); 


METHOD 4: USING DESCRIPTORS 





Dynamically defined queries cannot be executed. using simply the PRE- 
PARE and EXECUTE statements. A query returns its results into a set 
of host variables, but the SELECT list is not known until the user enters 
a query at a terminal. Therefore, the number and type of host variables 
cannot be predetermined by the programmer. This is not necessarily a 
handicap, because in being able to anticipate and programmatically handle 
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any situation, a programmer can write very flexible and powerful host- 
language programs to access a database. 


To write a program to accommodate dynamic queries as well as other SQL 
statements, you use cursors in conjunction with the DESCRIBE statement. 


The DESCRIBE statement examines the SELECT list of a query after it 
has been prepareded by a user and determines 


o the number of columns in the query’s result 
è the datatype of each column. 


Then the program can dynamically allocate a storage area to hold one row 
of the query’s result. Just as in pre-programmed queries, a cursor is asso- 
ciated with the dynamic query, and rows of the result are read from the 
storage area, using the cursor commands OPEN, FETCH, and CLOSE. 


For a review of the cursor commands for non-dynamic queries, see “Using 
Cursors”. 


The DESCRIBE statement works for any prepared SQL statement, not just 
queries. Thus, programs for dynamically-entered SQL statements can 
handle non-queries as well as queries. 


The SQL Descriptor Area (SQLDA) 
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The storage area allocated by the DESCRIBE statement is called the SOL 
Descriptor Area or SQLDA. The SQLDA is never declared in the DE- 
CLARE section; it must be an automatic or static variable. The storage it 
points to is allocated dynamically at runtime. To declare the SQLDA, you 
can simply include the following declarative statement at the beginning of 
the program: 


EXEC SQL INCLUDE SQLDA; 


Like the SQLCA, it is permissible to code the SQLDA directly in the pro- 
gram rather than using the INCLUDE SQLDDA statement. If you do so, 
you can specify any name for the structure. 


The SQLDA is often used in two ways in a program: it is always used in 
queries to hold returned information about items in the SELECT list, and 
it can be used to hold information about input host variables (also known 
as bind variables). 


Thus, if a SQL statement has both define variables and bind variables then 
two SQLDAs are required. In addition, if a program has more than one 

















active SQL statement (for example, two or more cursors open), then each 
SQL statement must have its own appropriate SQLDA(s). Non- 
concurrent cursors can re-use SQLDAs. 


For example, the following DML statement: 


EXEC SQL DELETE FROM TABA WHERE C1 = :v1 AND C2 = :v2 


requires one SQLDA containing two entries (one for v1 and one for v2). 
The following SQL statement (a query) requires two SQLDAs, one for the 
define variables (two entries: d] and d2), and one for the bind variables 


(also two entries: x1 and y2): 


EXEC SQL SELECT C1, C2 
INTO :di, :d2 
FROM TABB 
WHERE C3 = :x1 AND C4 = :y2; 


Thus, ORACLE RDBMS returns information via the SQLDA, but the 
program also puts information into the SQLDA. 


When the SQLDA is used in both ways, the name of the SQLDA can be 
chosen to indicate its use (as in SELECTDA for the former, and BINDDA 
for the latter, use), as shown in the following example: 


EXEC SQL INCLUDE SQLDA; 
SQLDA *bindda, *selectda 
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The Meaning of SQLDA’s Individual Elements 


The structure of the SQLDA in Pro*C is shown in Figure 10. 





struct sqlida { 
int N; /* 
—>char **Y; /* 
int kal Sa Ae 
short *T; /* 
-Short **I; /* 
int F; /* 
—schar **S; /* 
short *M; /* 
short *C; /* 
-char **X; /* 
short *Y; /* 
short *Z; /* 





}; 
typedef struct 
L- 


Descriptor size in number of entries Y 
Ptr to Arr of addresses of main variables*/ 
Ptr to Arr of lengths of buffers */ 
Ptr to Arr of types of buffers xy; 


Ptr to Arr of addresses of indicator vars*/ 
Number of variables found by DESCRIBE */ 
Ptr to Arr of variable name pointers xy 
Ptr to Arr of max lengths of var. names */ 
Ptr to Arr of current lengths of var.names*/ 
Ptr to Arr of ind. var. name pointers */ 
Ptr to Arr of max lengths of ind. var. names*/ 
Ptr to Arr of cur lengths of ind. var. names*/ 


sqlda sqlda; 








Figure 10. The Structure of the SQLDA 


New DESCRIBE Behavior 
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Beginning with Version 1.1 of the ORACLE Programmatic Interfaces, the 
behavior of DESCRIBE, as used for bind and select descriptors, is more 

compatible with DB2. Primary changes are that DESCRIBE returns pre- 
cision and scale for NUMBERs and indicates NULL or NOT NULL data. 


Precision and scale are returned in the “length” word of the SELECT DE- 
SCRIPTOR (whose name is language dependent). Scale is the low byte, 
signed. Precision is the high byte, unsigned. In C, the “length” word is 
defined in SQLDA.H to be an int. However, it is treated as a 2-byte entity 
for purposes of extracting precision and scale. 


A utility function (available in the runtime library-- SQLLIB on VMS) will 
extract precision and scale, Though the following example is shown in C, 
the concepts apply to all languages: 








SQLDA *sdp; /* -> SELECT descriptor xy 
word prec; /* precision wig 
word scale; /* scale uf, 


extern VOID sqiprce(); /* Extract Precision and Scale */ 
sqiprc(&sdp->L[1],&prec, &scale); 


Note that the first argument in this function is the actual address of the 
length of the (i-1)tA variable in the select list. 


Note that all parameters are called by reference. 


The NULL/NOT NULL indication is returned in the “type” word of the 
select list descriptor, which is defined to be a short (2 bytes). If a column 
allows NULLs, then bit 2~ 15 (the high-order bit of the high-order byte) 
is set; else if column is NOT NULL, bit 2— 15 is clear. 


The ORACLE Programmatic Interfaces Runtime Library also contains a 
utility function for NULL: 


SQLDA *sdp; /* => SELECT descriptor */ 
word dty; /* datatype, sans NULL bit */ 
word nullok; /* 1 NULL; else 0 NOT NULL */ 


extern VOID sqlnul(); 
/* Extract Datatype and NULL Indication*/ 


sqlnul(&sdp->TL i], &dty, &nul lok); 
if ( nullok ) 


{/* NULL's allowed. */ 
} 


Again, note that parameters are passed by reference. 


The following is also legal and useful for disposing of the NULL bit: 
sqlnul(&sdp->T[i],&sdp->T[i],&nullok); 


It is likely that all existing programs using DESCRIBE will have to be al- 
tered, due to the possibility that: 
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e Any ORACLE datatype can now be returned by DESCRIBE (a 
change from previous versions, which only return CHAR and NUM- 
BER). 


e The added NULL/NOT NULL bit in datatype means that tests for 
specific ORACLE datatypes can fail due to the new bit. 


e NUMBER columns must be coerced to some datatype (CHAR or 
VARCHAR are the safest). This is due to the fact that the internal 
representation for NUMBER is datatype that cannot be manipulated 
by the user. 


e If you coerce columns to CHAR so you can display them, the change 
in the way the length word is returned for NUMBERs means that you 
MUST look at the precision and scale bytes to know how much space 
to allocate. The algorithm is: 


len = prec; 


if ( prec == 0 ) 
{/* Have NUMBER (i.e., no precision/scale). Use default. */ 
Jen = 40; /* 40 is the maximum value supported. */ 


} 


else if ( scale < 0 ) 
{/* Have -scale. Need to pad w/ trailing zeros. */ 
len = len + (-scale); 


} 
len = len + 2; /* +2 for possible sign and decimal pt */ 


e If you coerce DATE columns to CHAR so you can display them, you 
must allocate 9 chars for default DATE format of DD-MON-YY. 


¢ For LONG or LONG RAW cols, the length returned is 0, so you 
must either allocate a maximum or pick a maximum. In addition, you 
must coerce to VARCHAR to get the length on fetch. Note that this 
does not work across SQL*Net for LONG RAW on heterogeneous 
machines that perform character set conversions (e.g., ASCII to/from 
EBCDIC). There is no current workaround to this problem. 


The following table shows types that can be returned (SQLTYPB), their 
binary/DESCRIBE’d length (DSCLEN), and their 
display/coerced-to-CHAR len (DSPLEN). 
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CHAR 1 A A 
DATE 12 7 9 
DATE (d) 13 7 9 
LONG 8 0 B 
LONG RAW 24 0 B 
NUMBER 2 c c 
RAW 23 A A 
ROWID 11 13 18 

Notes: 

A. DSCLEN and DSPLEN are equal to 
SYSCOLUMNS .WIDTH. 

B. DSPLEN for all LONG cols is variable because a 
fetched LONG COL has its own length (i.e., one 
length per row). Maximum length of a LONG col 
is operating system dependent (64K on VMS). 
See also note "A". 

C. See note above regarding precision and scale; 
and requirement that NUMBER be coerced to a 
user datatype. 

D. Due to a bug, DESCRIBE can return SQLTYPE=13 


COLTYPE SQLTYPE DSCLEN DSPLEN 


(internal date). This must be coerced to some- 
thing meaningful (usually DATE or CHAR). This 
bug can be seen by DESCRIBE'ing a DATE 
expression such as: TO_DATE('1-Mar-86') ~ 1. 





J 
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Note: You must clear the NULL/NOT NULL bit in the datatype before 
using the datatype in a subsequent OPEN, FETCH, etc. You must not set 
the NULL/NOT NULL bit under any circumstances; this would result in 
an error. 











Processing a Runtime Query 


The steps of running a runtime query are summarized in Figure 11. 


1. Declare the SQLDA structure. 

2. Prepare the SQL statement entered by the user. 

. Declare a cursor for statement name. 

. Allocate an instance of the SOLDA. 

Deallocate storage for the SQLDA. 

. Describe bind variables INTO the bind-SQLDA. 
Open cursor. 

. Describe SELECT list INTO the select-SQLDA. 
. Fetch until the end of result. 10. Close cursor. 





WO OOM DA BW 





Figure 11. Steps for Processing a Runtime (Dynamic) Query 


The following sections describe allocating and deallocating descriptors, and 
initializing and using the fields of the descriptors. 


The steps in writing a Pro*C program to respond to any SQL statement 
are described below. Also, Appendix E contains a well-commented Pro*C 
program to accept dynamic SQL statements. It illustrates the concepts 
which are discussed in following sections and can be used for reference 
while writing Pro*C programs. 


Preparing the SQL Statement 
PREPARE does two things: it parses the SQL statement, and associates 
a name with the statement (the stalement-name). Note that, like static 
queries returning more than one row, the SELECT may not contain an 
INTO clause. 


The SQL statement is read into a host variable; this host variable is declared 


in the DECLARE section. The PREPARE statement associates that var- 
iable with a statement-name; the statement-name is not declared. 


Declare a Cursor for the Statement 
When declaring a cursor for static SQL queries, the syntax is: 


EXEC SQL DECLARE cursorname CURSOR FOR query; 


When declaring a cursor for dynamic SQL queries, the statement-name is 





substituted for the static query. 
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EXEC SQL DECLARE cursorname CURSOR FOR statementname; 


where the statement-name is the one used in the PREPARE statement. 


Allocating a Descriptor 
To allocate a descriptor, use the routine sqlald: 


sqlda_name = sqlald (a, b, c) 


where: 

a is the number of variables to be described 

b is the size of strings to hold main variable names (the maximum 
length of host variable names) 

c is the size of strings to hold indicator variable names (maximum 


length of indicator variable names). 


The routine sqlald allocates the descriptor structure in addition to each of 
the arrays pointed to by the fields: V, L, T, and I. 1f b is non-zero, arrays 
pointed to by fields S, M, and C are allocated, along with space for main 
variables. If cis non-zero, arrays pointed to by fields X, Y, and Z are al- 
located, along with space for indicator variables. If b and c are zero, no 
space for S,M,C, and /or X,Y, or Z is allocated. 


If sqlald succeeds, it returns a pointer to the structure. If sqlald fails, it re- 
turns (struct sqida *)0. If sqlda-f is less than 0, the DESCRIBE found more 
items than a(above) allowed. Call sqlda with the descriptor address and re- 
call sqlald with correct parameters. 


De-allocating a Descriptor 
To de-allocate a descriptor, use the routine sq/clu, supplying a pointer to 
the descriptor to be deallocated: 
sqiclu(sqlda_name); 


The descriptor must have been allocated using sqlald; if it was not allocated 
using sqlald the results are unpredictable. 


Describing the Bind Descriptor 
The input, or bind descriptor, is used to store the input variables used in 
evaluating the SQL statement. 


EXEC SQL DESCRIBE BIND FOR statement-name INTO sqida_name; 
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Opening the Cursor 


For example, if the SQL statement entered were: 
INSERT INTO EMP (EMPNO, ENAME) VALUES (:empno, :ename); 


then the values the user also enters, for :empno and :ename, are stored in 
the bind descriptor, and used in the OPEN. 


The DESCRIBE BIND must occur after the PREPARE and before the 
OPEN. 


The OPEN cursor statement used for dynamic queries is similar to that 
used for static queries: 


EXEC SQL OPEN cursorname; 


For dynamic queries (or any dynamic SQL statement) the cursor is associ- 
ated with a bind descriptor: 


EXEC SQL OPEN cursorname USING DESCRIPTOR sqida_name; 


Thus, the values input by the user and stored by the bind descriptor are 
used as bind variables, to evaluate the query and identify its active set. 
(Remember, the actual query or SQL statement is associated with the cur- 
sor in the DECLARE CURSOR statement.) In the event that the SQL 
statement is not a query, then we are finished. However, for SQL queries 
(SELECT statements), we must continue with fetches to actually retrieve 
rows. 


Describing the Select Descriptor 


If the dynamic SQL statement is a query, then a DESCRIBE statement is 
required to associate items in the SELECT list with an ouput descriptor: 


EXEC SQL DESCRIBE SELECT LIST FOR statementname 
INTO outputdescriptor; 


The DESCRIBE SELECT must occur after the PREPARE, DESCRIBE 
BIND, and OPEN, and before the FETCH. 


Fetching Rows from the Active Set 


The FETCH statement returns a single row from the active set. Whereas 
the FETCH statement for static queries is: 


EXEC SQL FETCH cursorname INTO outputhostvariables; 
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the FETCH statement for dynamic statements is: 
EXEC SQL FETCH cursor_name USING DESCRIPTOR outputdescriptorname; 


The only difference is that rows are returned using the specified output de- 
scriptor. 


Closing the Cursor 
The cursor for dynamic queries is closed just the same as for static queries: 


EXEC SQL CLOSE cursorname; 
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CHAPTER 7. INVOKING PRO*C (THE PRECOMPILER COMMAND) 





The precompiler command and its options are described in this chapter. 


REQUIREMENTS FOR RUNNING PRO*C 





The main requirement for running Pro*C is that you have an input file to 
precompile. The sole required argument is the name of the file, assuming 
that you've used standard host language file naming conventions. If you 
use different extensions or filetypes, then you must also specify the host 
language. 


SETTING THE DIRECTORY OR PATH 





If your operating system uses directories or paths, be sure that the 
path/directory name, including the device, is valid. Pro*C creates a tem- 
porary file during execution, and will abort if it cannot open the file (as 
would be the case if a pathname had a mismatch between the device and 
directory). 


Furthermore, if the directory where the temporary file is written is nearing 
full, Pro*C may encounter problems writing the entire file. If your output 
files appear to be missing data, try deleting some files in that directory and 
re-precompiling your program. 
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CHANGES IN VERSION 5.1 OF PRO*C 





COMMAND SYNTAX 


Note that changes in the runtime library versions require that you re- 
precompile programs when moving from Version 4 of ORACLE to version 
5.0 of the ORACLE RDBMS. In general, it is not possible to cross- 
compile a program on one machine with a different type of target machine; 
rather, the program must be re-precompiled on one system and moved to 
another system with the same hardware and operating system. 


In addition, Version 1 precompilers linked to Version 5 of the ORACLE 
RDBMS differ from earlier versions in that they are no longer linked to 
ORACLE. The advantage to this is that the precompilers can be used in- 
dependently of any ORACLE database. Another consequence of this 
change is that during runtime, the precompilers do not do any SQL syntax 
checking, nor do they check for valid table or column names. Instead, such 
errors are detected when the program is run. 





Required Arguments 


To see an online display of the valid command options, simply enter: 


PCC 
That display, showing the command, syntax, options, and defaults, sum- 
marizes information in the following sections. ‘The general command syn- 
tax is: 


PCC INAME = filename {option=value (option=value 3 





112 / Pro*C User's Guide 


Only one argument is required: INAME = filename. If no file extension 
or type is given, then the argument HOST = language must be used, Null 
file extensions may be specified by leaving a trailing period. 


Figure 12 on page 113 shows, by operating system, the default file type or 
extension which Pro*C expects for input files, and returns for output files. 








If you do not indicate the input file’s type or extension, then you must use 
the HOST = option. 








INPUT OUTPUT 
Operating File Type or File Type or 
System. Extension Extension 
VAX/VMS “pe -c 
IBM/VM/CMS csql c 
UNIX “pe c 


Figure 12. Pro*C Default File Specifications 





Pro*C Runtime Options 


Several options are available at runtime. The general format for specifying 
an option is: 


OPTION=value 


Some of the following options may be specified inline, rather than when 
invoking the precompiler. Those options are: 


AREASIZE 

ERRORS 

INCLUDE 

LITDELIM 
MAXLITERAL 
MAXOPENCURSORS 
REBIND 

XREF 


The EXEC ORACLE OPTION feature is particularly helpful in changing 
values used during precompilation -- for example, changing the 
AREASIZE on a cursor-by-cursor basis. It also helps alleviate problems 
on some operating systems which have limits on the number of characters 
which can appear in a command line. 


An option entered inline will override the same option entered on the 
command line. You can also place EXEC ORACLE options in a separate 
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AREASIZE 


ASACC 


BEGLABEL 


ENDLABEL 


ERRORS 


FORMAT 
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file and EXEC SQL INCLUDE them at the appropriate place in the pro- 
gram. 


This parameter specifies the context size for cursors opened by the program; 
the size specified by AREASIZE will override the context size specified in 
the INIT.ORA file. If the option is specified on the command line, it is 
used as the default size for all cursors within the Pro*C program. However, 
AREASIZE may be specified within the Pro*C program, multiple times, 
to changes the size of the next cursor or set of cursors. 


The areasize is specified in K-bytes; the default is 16. The areasize param- 
eter is actually only a minimum size; if a cursor requires more space than 
indicated in this parameter, Pro*C acquires more space, in increments as 
specified by the INIT.ORA parameter CONTEXT_INCR. 


This option specifies whether or not the listing file will follow ASA carriage 
contro! convention, using column 1 of each line for carriage control. De- 
fault is “no”; options are (yes,no). 


Not applicable for C. 


Not applicable for C. 


This option specifies where errors should be sent. Default is “yes”; options 
are (yes,no). If “yes”, errors are sent to both the terminal and list file. If 
“no”, errors are sent to just the list file. 


Not applicable for C. 








HOLD_CURSOR and RELEASE_CURSOR Options 


Two new options (HOLD_CURSOR and RELEASE_CURSOR) can be 
used to “tune” an application. These options allow programmers to control 
how a given SQL statement is handled in the cursor cache. Both options 

can be specified on the command line or by the EXEC ORACLE OP- 


TION. 





HOLD_CURSOR=YES | NO 


RELEASE_CURSOR=YES | NO 





HOLD_CURSOR = NO This is the default, and the way versions of the 
precompiler preceding V1.1 work. After a SQL statement that 
does NOT use a DECLAREd cursor executes (e.g., INSERT, 
DELETE, UPDATE), the cursor cache entry for this SQL state- 
ment is marked as “re-usable”. This means that this SQL state- 
ment’s cursor cache entry could get re-assigned for use by a 
different SQL statement. 


HOLD_CURSOR = YES If this setting is set to YES, the precompiler will 
not re-assign this SQL statement’s cache entry. This is useful for 
SQL statements which are used repeatedly and that you wish to 
keep active, because you avoid re-parses which would be neces- 
sary if the SQL statement’s cache entry were re-assigned. 


RELEASE_CURSOR = NO This is the default, and the way prior versions 
of the precompiler work. After a SQL statement that does NOT 
use a DECLAREd cursor executes (e.g., INSERT, DELETE, 
UPDATE), the cursor cache entry for this SQL statement is 
marked as “re-usable” -- however the cache entry is not released 
-- it is only released if another SQL statement causes this SQL 
statement’s cache entry to be re-assigned . 


RELEASE_CURSOR = YES If set to YES, the PCC will always release 
the cursor cache entry for a SQL statement after an execute. This 
means that every execution of this SQL statement will cause a 
re-parse, etc. This is useful for telling the PCC that this SQL 
statement is not executed very often, and therefore you don’t want 
it to hold database/cursor cache resources. 


In the following example, no cursor cache entry is held for the SQL state- 
ment: 
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OP MlliŘŘŘŮŮŮŮ—— 


EXEC ORACLE OPTION (RELEASE_CURSOR=YES); 
EXEC SQL SELECT DNAME 

INTO — : NAME 

FROM DEPT 

WHERE DEPTNO = :NR; 
EXEC ORACLE OPTION (RELEASE_CURSOR=NO); 


Thus every execution of the statement will cause a re-parse, etc. Note that 
the default, RELEASE_CURSOR= NO, is reset after SQL statement. 
Whereas in the following example: 


EXEC ORACLE OPTION (HOLD_CURSOR=YES); 
EXEC SQL INSERT INTO EMP (ENAME, EMPNO, SAL, DEPTNO) 

VALUES (:ENAME-VAR, : EMPNO-VAR, : SAL~VAR, : DEPTNO-VAR); | 
EXEC ORACLE OPTION (HOLD_CURSOR=NO); 


the SQL statement retains its cursor cache entry and will parse only once 
no matter what happens in the program. 


Typically, you would use RELEASE_CURSOR = YES for infrequently 
executed SQL statements, and HOLD_CURSOR = YES for frequently 
executed SOL statements. These options can significantly affect program 
performance depending on how successful you are at picking a reasonable 
combination of HOLD_CURSOR, RELEASE_CURSOR, and 
MAXOPENCURSORS. 


HOST 
This option specifies the host language of the input program. Options are 
(c/cobol/fortran/pli). This parameter is required if no file extension or file 
type is entered on the command line; if a standard file extension or file type 
i entered as part of the file name, this parameter is optional. There is no 
efault. 


INCLUDE 
This option specifies a pathname for EXEC SQL include files (only appli- 
cable for operating systems using paths). For example, the following might 
be entered for a xxx system: 


PCC INAME=abc INCLUDE= xxx/s/b/c 
There is no default for INCLUDE. 


You may specify INCLUDE = dira INCLUDE = dirb, etc. This will search 
first in your local directory, then in dira, and finally, in dirb. 


116 / Pro*C User’s Guide 








nn ——— 


IRECLEN 


LITDELIM 


LNAME 


LRECLEN 


LTYPE 


MAXLITERAL 


MAXOPENCURSORS 


This option specifies the record length of the input file. Default is 80; the 
maximum is 132. The IRECLEN should be equal to or less than the 
ORECLEN. 


Not applicable for C. 


This option specifies the delimiter for COBOL nonnumeric literals. 
Options are (apost, quote); the default is “quote”. 


This option is used to specify a filename for the output listing file other than 
the default which will be created (INAME.LIS or INAME LIST). The 
listing file is written to the current directory or A-disk. For example, to 
specify a different output file, you might enter: 


PCC INAME=BANJO,PC LNAME=VIOLIN. LIS 


This option specifies the record length of the listing file. Default is 132; 
valid entries are _ to__. 


This option specifies the listing type. Options are (long, short, none); de- 
fault is “long”. If “long” is used, the input lines appear in the listing file; if 
“short” is used, they do not appear. If you specify “none”, no listing file is 
created, 


This option is used to accommodate certain compiler restrictions on the 
maximum string lengths. If necessary during precompilation, Pro*C will 
divide strings exceeding this setting into strings of this length, and recon- 
struct the strings after precompilation. The default setting is language de- 
pendent (1000 for C). 


This option specifies the number of simultaneous open ORACLE cursors, 
or SQL statements that Pro*C will attempt to keep cached. Normally, 
rather than opening an ORACLE Cursor for each Pro*C cursor, Pro*C 
tries to re-use different ORACLE cursors in the same ORACLE Cursor 
Data Area. Pro*C will actually use however many cursors are necessary 
even if that number exceeds MAXOPENCURSORS (by temporarily ac- 
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ORACA 


ORECLEN 


PAGELEN 


REBIND 
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quiring extra cursors when necessary). The default is 10, which is fine for 
most programs which use relatively few simultaneous open cursors. 


The maximum number of MAXOPENCURSORS is operating system 
dependent (and the limit is set in the INIT.ORA file). ORACLE RDBMS 
requires an overhead of 5 ORACLE cursors. Using 
MAXOPENCURSORS you can override the parameter to a lower num- 
ber, but you will get an error if you set MAXOPENCURSORS to a higher 
number. 


If your program uses many simultaneous SQL statements, you may wish 
to increase MAXOPENCURSORS so that the maximum number of open 
ORACLE cursors matches the maximum number of Pro*C cursors re- 
quired by the program. A setting of 45 to 50 is not uncommon, but re- 
member that each cursor requires additional context space in the user 
process, 


This option specifies the name of the output file. By default it is INAME.C 
(or INAME C under VM/CMS). The output file is written to the current 
directory or to the A-disk. 


This option specifies whether or not this program can use the ORACLE 
communications Area. The options are “yes” and “no”; “no” is default. 
You must also INCLUDE the ORACA using the statement-- 


EXEC SQL INCLUDE ORACA 


This option specifies the record length of the output file, Default is 80; the 
maximum is 132. The IRECLEN should be equal to or less than the 
ORECLEN. 


This option specifies the number of lines per physical page. The Default is 
66. 


This option controls the way Pro*C handles Binds and Defines. The 
options are “yes” and “no”. YES directs the precompiler to generate code 
that rebinds all INTO and USING variables on every execution of a SQL 
statement. “Yes” is the default. “No” directs the precompiler to generate 





a ee 


SELECT_ERROR 


code that will only bind INTO and USING variables once-per-parse (Le., 
once pet open ORACLE cursor). Normally, this means once per program. 


Though there was no equivalent parameter in ORACLE V4, the precom- 
pilers used to generate code that was equivalent to REBIND=NO. The 
problem was that INTO/USING variables that were passed as parameters 
into a subroutine that contained a SQL statement which referenced those 
INTO/USING variables worked incorrectly; because the INTO/USING 
variables were only bound once, only the first set of parameters were bound 
into the SQL statement. 


The default, REBIND = YES, should work for all cases (subroutine or 
not). However, rebinding can be suboptimal, effecting performance and 
cost, and so users who don’t require the generality of rebinding should se- 
lect REBIND= NO. 


This option controls whether the precompiler will generate an extra fetch 
call on single row queries to detect if more than one row could have been 
fetched. Options are “yes” (the default) and “no”. A change made for 
compatibility with IBM’s database product DB2 affects the use of SELECT 
.. INTO. Given the statement: 


EXEC SQL SELECT ENAME 
INTO ;ename 
FROM EMP 


If the query returns more rows than will fit in ename SQLCODE will be 
set to OER 2112: 


PCC: SELECT ... INTO returns too many rows 
If ename is a scalar, then SQLCODE is set if more than one row satisfies 


the query. If ename is an array, then SQLCODE is set if the result over- 
flows the array. 


To perform this check, the precompiler must generate an extra fetch, thus 
costing some in performance. A command line option enables checking: 


SELECT_ERROR= [ YES | NO ] 


where: 


YES enables checking and errors will generate the error message. The 
default is “yes”. 
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NO indicates that the precompiler should not generate an error if a 
SELECT .., INTO returns too many rows. This behavior is 
compatible with earlier versions of the ORACLE Programmatic 
Interfaces. 


USERID 
This option specifies an ORACLE username and password. There is no 
default. Do not specify if you are using the automatic logon feature 
(ORACLE usernames prefixed with OPS$). Although this option is ac- 
cepted by Pro*C, it is not a valid command in Version 5.1. 

XREF 


This option specifies whether a cross reference section should be included 
in the listing file. Default is “yes”; options are (yes,no). Cross references 
are included for host variables, cursor names, and statement names. 


Example Program Using REBIND 
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/* Example #16 */ 
#include <stdio.h> 


This is a sample Pro*C program which shows the use of 
the option REBIND. 


EXEC SQL BEGIN DECLARE SECTION; 


VARCHAR uid[ 20]; 
VARCHAR pwd[ 20]; 
int empno; 

int deptno; 

char ename[ 15]; 
float sal; 


EXEC SQL END DECLARE SECTION; 


EXEC SQL INCLUDE SQLCA; 


main() 


int answer 
char ans; 


/* log into ORACLE */ 


strepy(uid.arr, "SCOTT" ); /* copy the user name */ 
uid. len=strlen(uid.arr); 
strcpy(pwd.arr, "TIGER" ); /* copy the password */ 


pwd. len=strlen(pwd.arr); 


EXEC SQL WHENEVER SQLERROR GOTO errrpt; 
EXEC SQL CONNECT :uid IDENTIFIED BY : pwd; 


printf("Connected to ORACLE as user: %s \n",uid.arr); 
printf("Do you want to query by employee number <Y/N>? "); 


answer = getchar(); 
ans = answer; /* convert it back to character */ 
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i (Cans H= 'y') && (ans, ]= 'Y')) 


EXEC SQL WHENEVER NOT FOUND GOTO endloop; 
EXEC ORACLE OPTION (REBIND=N0); 


EXEC SQL DECLARE C1 CURSOR FOR 
SELECT ENAME, SAL, DEPTNO 


FROM EMP; 
EXEC SQL OPEN C1; 
printf("\n\nName Dept Salary\n"); 
printé ("nnn nena FERL. tara \n\n"); 
while(1) /* do this for a long time */ 


EXEC SQL FETCH C1 INTO :ename,:sal,:deptno; 
printf("%.15s %4d %6.2f\n",ename,deptno,sal); 


} 


else 


{ 
EXEC SQL WHENEVER NOT FOUND CONTINUE; 
for (;; ) 


printf("Enter employee number to query on (0 to end): "); 
sret = scanf("%d", &empno); 
if (sret == EOF !! sret == 0 !! empno == 0) 
break; 
EXEC ORACLE OPTION (REBIND = YES); 
EXEC SQL SELECT ENAME, SAL, DEPTNO 
INTO :ename,:sal,:deptno 
FROM EMP 
WHERE EMPNO = :empno; 
printf("Employee: %.15s Department: %4d Salary: %6.2f\n", 
ename,deptno, sal); 
} 
} 


endloop: 
printf("\n\nProgram completed. \n"); 
EXEC SQL WHENEVER SQLERROR CONTINUE; 
EXEC SQL COMMIT WORK RELEASE; /* log off database */ 
exit(0); 
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errrpt: 


printf("\n %.70s \n",sqlca.sqlerrm. sqlerrmc); 
EXEC SQL ROLLBACK WORK RELEASE; /* log off database */ 
exit(1); 
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COMPILING AND LINKING 


Refer to the Installation and User's Guide for your operating system for 
instructions on compiling and link-editing the output of your Pro*C pro- 
grams. 


CONDITIONAL PRECOMPILATION 


Conditional precompilation is the inclusion or exclusion of portions of code 
based upon the existence of certain conditions (such as, including a section 
of code when precompiling under CMS or including other code if precom- 
piling under VMS). The advantage of conditional precompilation is that 
you can write programs which can run under several environments, using 
conditional statements to distinguish sections of code relevant to single en- 
vironments. 


Sections which are conditional are marked by statements which define the 
environment and actions to take. Programming language statements as well 
as EXEC SQL statements can be included in the conditional sections. 


Precompilation control is supported with the following statements: 


STATEMENT DEFINITION 

EXEC ORACLE DEFINE symbol; define a symbol 

EXEC ORACLE IFDEF symbol; if symbol is defined 

EXEC ORACLE IFNDEF symbol; if symbol is not defined 
EXEC ORACLE ELSE; otherwise 

EXEC ORACLE ENDIF; terminate this control block 


Symbols may be defined in one of two ways: 


e Include the following statement at least once in the source program: 


EXEC ORACLE DEFINE symbol: 
e Define the symbol on the command line, as in: 


PCC INAME=xyz .... DEFINE=symbo] 
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Several symbols are currently pre-defined.. These are port specific and are 
defined at the time the ORACLE Programmatic Interfaces are built on a 
given system. 


Operating System Hardware 
CMS IBM 

MVS DEC 
MSDOS 

UNIX 

VMS 


The following is an example of how to control precompilation. 


EXEC ORACLE IFDEF testcase; 
EXEC SQL SELECT COUNT(*) INTO counter FROM EMP; 
EXEC ORACLE ENDIF; 


In the above example, the select statement will only be precompiled when 
the symbol “testcase” is defined, either within the Pro*C program or on the 
command line. The precompiler will comment out C code as well as 
EXEC SQL or EXEC ORACLE statements. 


Blocks of conditions may be nested as in: 


EXEC ORACLE IFDEF xyz; 
EXEC ORACLE IFDEF abc; 


EXEC ORACLE ENDIF; 


There are no case distinctions within symbols, as Pro*C will convert the 
symbol name to upper case. 


These precompilation control statements are almost functionally equivalent 
to C preprocessor control statements. 
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SEPARATE PRECOMPILATION 


Several Pro*C programs can be separately precompiled, and linked together 
in one executable program. The individual programs need not be written 

in the same language. Furthermore, if the program will be run on a differ- 
ent CPU than where it was precompiled, it need not be re-PCC’ed, but in 
fact can be distributed in the executable form (for example, the .EXE files). 


To precompile several files, follow these guidelines: 


L 
2. 


Precompile each file separately. 


Make sure all definitions and references to any given cursor occur in 
only one file. That is, you cannot DECLARE a cursor in one file, and 
OPEN or FETCH from it in another file which was separately pre- 
compiled. 


The SQLCA and SQLDA can be passed as parameters, or can be ex- 
ternals. In the latter case, you must INCLUDE their definition. 


When you precompile the file which does the CONNECT, use the 
maximum number of MAXOPENCURSORS you will desire for any 
of the files. The option MAXOPENCURSORS, if used on any of the 
other separately precompiled modules, will be ignored; the setting in 
effect for the CONNECT determines the actual number used at 
runtime. 


MIXING PRO*C AND ORACLE CALL INTERFACE PROGRAMS 
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Pro*C and OCI statements can be written into the same program file. 
There is no sharing of Pro*C ORACLE cursors and OCI ORACLE cur- 
sors. If you mix Pro*C and OCI statements in the same file, keep the fol- 
lowing requirements in mind: 


° 


The Pro*C program must perform the logon (CONNECT) 


EXEC SQL CONNECT :oracleid IDENTIFIED BY : password 


After connecting, the program must insert a call to a SQLLIB routine, 
to set up the Pro*SQL Logon Data Area, by entering: 


sqlida( da); joa 








et A 


where /da is the address of the Logon Data Area, as in standard 
Pro*SQL programs. 


By following this convention, both Pro*C and OCI “know” that they are 
“working together”. 


For some operating systems, the call to the SQLLIB will vary. For exam- 
ple, for IBM/VM/CMS it is: 

sq2da(1da) 
Check the ORACLE Database Administrator's Guide for your particular 
operating system. 


For a complete guide to writing OCI programs, refer to Part II of this 
manual, 


WHAT OCCURS DURING PRECOMPILATION? 





During precompilation Pro*C generates C code sequences in the applica- 
tion program that avoid re-parses and re-binds if they are found to be un- 
necessary. (This information is kept in the cursor cache.) 


Runtime Consistency Checking 


Pro*C’s runtime library performs runtime consistency checking; thus you 
may get some runtime error messages from SQLLIB. Runtime errors are 
returned via the standard SQLCA structure (just like ORACLE RDBMS 
errors). See Appendix A for those errors. 
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PART Il: THE PRO*C ORACLE CALL 
INTERFACE 








As mentioned in the Preface, Pro*C provides a programmatic interface that 
allows ORACLE calls to be made directly from a high-level language. This 
interface is called the ORACLE Call Interface, or OCI, and was previously 
known as the High Level Interface, or HLI. The OCI provides a great deal 
of flexibility for programmers who are developing applications that define 
and manipulate the data in an ORACLE RDBMS, 


Programmers who are familiar with the Pro*SQL User's Guide should note 
that the information in this part of the manual is almost identical to the 
Pro*SQL User's Guide. Unlike the Pro*SQL User's Guide, however, the 
examples included here pertain only to C. In addition, this manual uses 
different terminology to identify a program that uses the OCI. In previous 
versions of the Pro*SQL User's Guide all high-level language programs tha 
included OCI(or HLI) procedures were referred to as Pro*SQL programs. 
This manual refers to any high-level program that uses the OCI as a C/OCI 
program, When referring to general concepts that apply to all high-level 
language programs that use OCI calls, the term OCI program is used. For 
information on using the OCI with other high-level languages, refer to the 
user’s guide for that language. 


The chapters that follow present a complete description of the ORACLE 
Call Interface. Chapter 8 describes the structure of an OCI program. 
Chapter 9 gives complete information on each OCI call, and includes ex- 
amples that show how to express each OCI call in C. Chapter 10 describes 
the OCI calls provided by earlier versions of Pro*SQL. Chapter 11 presents 
information on supported datatypes and datatype conversions. Appendix 
F of this manual presents a complete C program that uses the OCI. 
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| CHAPTER 8. INTRODUCTION TO WRITING AN ORACLE CALL INTERFACE 
PROGRAM 
A 





| This chapter introduces concepts used in writing an ORACLE Call Inter- 
| face program, such as cursor data area, logon data area, return codes, types 
| of parameters, program structure, and gives a brief summary of the calls. 


The SQL data language is a non-procedural language. That is, most state- 
ments are executed independently of preceding or following statements. 
Compare this to programming languages, such as COBOL, FORTRAN, 
or C. Those languages, called procedural, are based on constructs such as 
“oops”, “branches”, and “if/then” pairs. Whereas the SQL language is a 
very powerful one, nevertheless it has some limitations without procedural 
capabilities. 


Having specifically designed SQL to be a non-procedural language, and 
understanding the limitations of such a language, the originators of SQL 
also explicitly designed SQL constructs to be embedded in procedural pro- 
gramming languages. With these constructs, called program calls, pro- 
grammers can write applications which combine the best features of SQL 
and the best features of the programming language. These applications can 
be more powerful and flexible than applications written in either the host 
language or SQL alone. 


ORACLE may be interfaced to FORTRAN, COBOL, C and other pro- 
gramming languages by means of these program calls. All SQL query, data 
manipulation, data definition, and data control facilities are available from 
both the interactive and programming interfaces (SQL*Plus and the 
ORACLE Call Interface respectively). 
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eV 
BASIC PROGRAM STRUCTURE 
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A program establishes communication with ORACLE RDBMS by issuing 
the OLON call. Communication takes place via the Logon Data Area 
(LDA) defined within the user program. A user program issues one and 
only one logon to ORACLE. 


A cursor is the name of a data area is used to identify and control an active 
SQL statement. The cursor data area is defined within the user program. 
ORACLE permits user programs to have multiple active SQL statements. 
This is accomplished by a single program issuing multiple OOPEN’s to 
establish multiple cursors. 


The OSQL3 call associates a SQL statement with a cursor. Subsequent 
calls for that SQL statement reference that cursor name. For example, the 
OEXEC call executes the SQL statement. In the case of a query, the 
OSQL3 call defines a set of rows to be retrieved (the active set) and logically 
positions the cursor just before the first row. Then OFETCH retrieves the 
individual rows of the active set. 


Figure 13 on page 133 shows the flow and calls used to program a SQL 
query in an OCI program. 
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OBNDRV 
or 
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OEXE 


| 

V 
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V 
cael 


V 
OLOGOF 


Establish the Logon Data Area | 
Open a Cursor Data Area 


Associate a SQL statement with a 
Cursor and parse the statement 


Define a program buffer area to 
store the items from the select-list 
(There must be one ODEFIN call for 
each item in the list.) 


Pass the address of program 
variables used in the SQL statement 
to ORACLE (one call per variable) 


Execute the current SQL statement 
in the specified Cursor 


Return one row from the ORACLE table(s) 
into the program buffer area(s) defined 
by the ODEFIN call 


If not end-of-fetch: 
return to the OFETCH call to get the 
next row 
If all rows have been fetched: 
If another SQL statement: 
go to OSQL3 
If another BIND variable: 
change program variable 
go to OEXE 
Else close Cursor 


Disconnect from ORACLE 





Figure 13. OCI Program Logic for a SQL Query 
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Every OCI program is protected from data integrity loss by ORACLE’s 
automatic rollback/recovery mechanism. There are calls to COMMIT and 
ROLLBACK transactions and calls to set non-fatal error recovery mech- 
anisms. 


A summary of the calls discussed in this guide appears in Figure 14 on page 
135. 
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Call Name Call Purpose 

OLON Connect to ORACLE. 

ORLON Establish concurrent connections to ORACLE. 

OOPEN Create a cursor, 

OSQL3 Pass a SQL statement to ORACLE. 

ODSC Determine the type, size, name, and status of a column ina 
SQL statement, 

ONAME Determine the name of a column in a SQL statement, 

QDEFIN Identify the location and type of an area in the program 
to receive data from ORACLE (array define), 

OBNDRV Substitute data from the user program into a SQI. | 
statement variable (array bind). : 

OBNDRN Substitute data from the user program into a SQI 
statement variable (array bind). 

QOPT Choose options for multi-row non-fatal error recovery. 

OBXEC Process a SQL statement. 

OEXN Allows operations using an array of bind variables. 

ORES Not supported. 

OFETCH Retrieve data into defined data areas one row at a time, 

OFEN Fetches multiple rows into an array of define variables with 
single call. 

OBREAK Terminate the current ORACLE function, 

OCAN Indicate that the current function is complete, 
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Call Name Call Purpose (continued) 

OCOM Commit the current transaction to the database. 
OROL Rollback the current transaction from the database, 
OCON Enable automatic commits. 

OCOF Disable automatic commits, 

OERMSG Retrieve message text of an ORACLE error number, 
OCMN Not supported. 

OCLOSE Delete a cursor. 

OLOGOF Disconnect from ORACLE, 





Figure I4. Program Call Summary 
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THE CURSOR DATA AREA 





The cursor is a 64-byte data area, associated with an active SQL statement 
and defined within a user program. A cursor is identified to ORACLE 
(named) in an OOPEN call. Every subsequent ORACLE call referencing 
that SQL statement uses the cursor’s name. The cursor data area contains 
status information on an active SQL operation. 


A program can have multiple cursors. The maximum number of cursors 
that may be opened at once is 150 minus those used by ORACLE (about 
5). The actual maximum at any particular time, however, depends upon . 
the memory available. 


The layout of the cursor data area is machine dependent because of the 
differences in C compilers. However, all fields and. values are present for 
all machines, Check the ORACLE Installation and User's Guide for your 
operating system to see exactly how the fields are named and numbered. 
The VAX/VMS cursor data area format is depicted in Figure 15 on page 
138; it is shown for example. Refer to the installation and. user's guide for 
your operating system to see the exact layout on your operating system. 


The layout, field Jengths, and byte orientations of the cursor data area are 
operating system dependent. Figure 19 applies for VAX/VMS, 
VAX/UNIX, and IBM. 
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E Eaa aa aa 
4 
j ROWS PROCESSED COUNT 
8 10 11 
PARSE ERROR OFFSET FUNC CODE} FILLER 
12 14 5 
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INTERAL ROWID OSD ERROR CODE 
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OSD ERROR CODE CHECK BYTE | ORAPARMS... 
ORACLE SYSTEM PARAMETERS -continued- 63 
thor re i a m e ee + ==- 


Figure 15. Layout of the Cursor Data Area 


Return Code Contains a two-byte binary number that indicates the completion code 
for the precompiler call. 


zero indicates a successful result. 


positive indicates a successful result with an exceptional condition. 
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negative indicates an error was cncountered trying to perform the specified 
operation. 


Several error codes are translated for ORACLE Version 2 compatibility. 
If you wish to see the untranslated codes, use the V4 ERROR CODE field. 








V2 Explanation V4 
+2 null column fetched 1405 
+3 column truncated by fetch 1406 
+4 end of fetch 1403 
-303 variable not in select-list 1007 
-9 duplicate value in index 1 
-605 bind variable does not exist 1006 





Other error return codes are listed in the ORACLE Error Messages and 
Codes Manual. (Also note that OERMSG is looking for a V2/V3 error 
code; however, negation of the V4 Error Code will also work.) 


Function Type Used internally in ORACLE, and subject to change between versions. 
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Value Type ] 
1 CREATE TABLE 
INSERT 

4 SELECT 

5 UPDATE 

7 DROP VIEW 

8 DROP TABLE 

9 DELETE 

10 DEFINE VIEW 

11 EXPAND 

18 CREATE CLUSTER 
20 CREATE INDEX 
21 DROP INDEX 

22 DROP CLUSTER 
23 CREATE SPACE 
24 ALTER SPACE 

25 DROP SPACE 

26 ALTER TABLE 

27 EVALUATE 

28 GRANT 

29 REVOKE 

30 CREATE SYNONYM 
31 DROP SYNONYM 








Rows Processed Count Contains a four-byte binary number indicating the count of 
the number of rows processed by a SQL operation. The count indicates 
the number of rows inserted, updated, or deleted by a data manipulation 
statement, or the number of rows fetched in a query statement. This field 
is valid only after an OEXEC or OFETCH call. 


Parse Error Offset Contains a two-byte binary number indicating the offset (in 
characters) of the parse error within the SQL, statement. This field is valid 
only after an OSQL or OSQL3 operation. 
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Function Code Contains a code indicating the OCI call requested. A function code 
exists for any OCI call which uses the cursor data area; calls referencing 
only the logon data area have no function code. 














Code Function 
02 OSQL 
04 OEXEC 
06 OBIND 
08 ODFINN 
10 ODSRBN 
12 OFETCH 
14 OOPEN 
16 OCLOSE 
22 ODSC 
24 ONAME 
26 OSQL3 
28 OBNDRV 
30 OBNDRN 
32 OOPT 

| 50 OBINDN 





V4 Error Code The Return Code field translates several ORACLE error codes to the 
numbers used in ORACLE Version 2, This field will always have the di- 
rect, current, untranslated ORACLE error message numbers as shown in 
the ORACLE Error Messages and Codes Manual. 


Flags! Bit warning flags. More than one may be set. 





Bit Value Meaning 


1 There is a warning. This is set 
when any other bit in FLAGS1 is 
set. 

2 Set if any data item was 
truncated on OFETCH. 

4 Set if NULL values were used in 
an aggregate function. 

16 Set if an update statement or 


delete statement is parsed 
without a where clause, 
64 Set if a ROLLBACK was performed. 
128 Set if inconsistent data fetched. 
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Flags2 More warning flags. 





Bit Value Meaning 


1 Unused. 

2 Set when a fatal error has 
occurred and the 
transaction was completely 
rolled back. 





4 Set when a rowlevel roll 
back was executed. 
8 Unused. 





Cursor Number Internal cursor number (a binary integer) used by ORACLE to track 
cursors used by different processes. 
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Internal ROWID The rowid in internal format. 





4 bytes: 
2 bytes: 
1 byte: 


4 bytes: 
2 bytes: 


RBA of the first block of the 
table (not implemented) 
partition number 

table identifier of the table 
in a cluster 

(not implemented) 

logical block 

row sequence 








The ROWID may be converted to hexadecimal and formatted to yield a 
character string which is identical to the ROWID returned using SQL SE- 
LECT statements. See the ORACLE Database Administrator's Guide for 
more information about ROWIDs. 


OSD Error Code The operating system dependent error code associated with an 
ORACLE error. For example, on VMS, if the ORACLE error is 509 
($write failure in BWR), then the OSD error code would have the actual 


VO system failure code. 


Check Byte A byte used to determine whether or not the cursor date area specified 


by the ORACLE call is valid. Its value is set by ORACLE and must never 


be modified by user programs. 


THE LOGON DATA AREA 


The logon data area (LDA) is a 64-byte area associated with each active 


connection (logon) to ORACLE. Its format is identical to the cursor data 


area, except that not all of the fields are used in the LDA. 
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RETURN CODE FILLER 
4 
FILLER 
8 10 11 
FILLER FILLER FILLER 
12 14 15 
V4 ERROR CODE 
32 33 
FILLER OSD ERROR CODE 
36 37 38 


OSD E. C. CHECK BYTE} ORAPARAMS 


The definitions are identical to those for the cursor data area. 
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PROGRAM INTERFACE DATA AREAS 


ORACLE allows a single program to have multiple ORACLE cursors 
open at the same time. 


To optimize program. performance, it is useful to have an understanding 
of the communication between ORACLE and a user program. 


The following is a diagram of a user program named UPDT3 with two 
open cursors. 

















USER PROGRAM ORACLE 
oe ee rte m e + pn i i ee i a + 
UPDT3 COMMUNICATION REGION 
spe iiaa + trenne + 
ORASTE + UPDT3 unused 
| LOGON LDA| PGA PGA 
econ cone + +--+ poet 
jc1} |c2| 
foccece + toc + sheep bet 
[OPEN C1] [OPEN C2| 
temme e a + 
SELECT UPDATE 
FROM SET ORACLE 
WHERE WHERE 
þrenn renen + fete er + 


When program UPDT3 issues the OLON call, ORACLE allocates a Pro- 
gram Global Area (PGA) for UPDT3. ORACLE connects this PGA to 
the logon data area (LDA) defined within program UPDT3. ORACLE 
will allocate one and only one PGA for each process (program) currently 
connected to ORACLE. 


When program UPDT3 issues an OOPEN call, ORACLE allocates a SQL 
Work Area (SWA) (or “context area”) for program UPDT3. ORACLE 
connects the SWA to the cursor (C1) defined within the UPDT3. 


When program UPDT3 issues a second QOPEN call, ORACLE allocates 
a second SWA and connects it to UPDT3’s second cursor (C2). ORACLE 
allocates one SWA for every open cursor. 
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The default size of each SWA is determined by the context_size parameter 
in the INIT.ORA file. The user may override the default by using the 
“areasize” parameter of the OOPEN call. The SWA must be large enough 
to contain the compiled SQL statement plus one row of data of the table 
or view being processed. 
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GENERAL CODING RULES 





Several different types of parameters can be used when calling ORACLE: 


address parameters pass the address of a parameter to ORACLE. Some 
address fields always refer to parameters of the same type, ¢.g., the 
LDA address of the OLON and OOPEN calls. Other address 
fields refer to parameters of differing types, e.g., the buffer address 
of the ODEFIN call. 


binary integer is a number whose size is the natural word size of the host 


computer. 
DEC VAX/VMS 32 bits 
IBM VM/CMS 32 bits 
DEC PDP-11 16 bits 


Check the ORACLE Installation and User's Guide for your oper- 
ating system for the size of a binary integer on your machine. 


short binary integer is a number whose size may be shorter than the natural 
word size of the host computer. 


DEC VAX/VMS 16 bits 
IBM VM/CMS 16 bits 
DEC PDP-11 16 bits 


Check the ORACLE Installation and User's Guide for your oper- 
emne system for the size of a short binary integer on your ma- 
chine. 


The following general rules apply to user programs calling ORACLE: 


Character strings may be null terminated, i.e., the last character is a char- 
acter containing all zero bits. If a string is not null terminated, then a length 
parameter must be specified (see “variable-length parameters”). Literal 
character strings may be used within the call parameter list if they are per- 
mitted by the compiler. Note that the use of a literal must generate a ref- 
erence to the literal as a result of the call. Please see the ORA CLE 
Installation and User's Guide for your machine for more information. 


Variable-length parameters are passed to ORACLE with an accompanying 
length parameter in the form: 


address parameter, binary integer 
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Optional Parameters 


Length parameters are binary integers specifying the size in bytes of the 
variable-length parameter. The length parameter may be omitted if the 
variable parameter is terminated by a binary zero. If the length is specified, 
then no scan for the binary zero is executed. 





Optional parameters are permitted only if the compiler in use permits 
missing parameters. If they are not permitted, then all parameters are 
mandatory. If a length field or other optional parameter is omitted from a 
call parameter list, the user may code comma comma (,,) to indicate the 
absence of the parameter, if the compiler permits it. For example: 


"parameterl, lengthl, parameter2, length2" 


versus 


"parameter, ,parameter2, ," 


In some languages (for example, C) the “comma-comma” notation is not 
allowed to indicate a missing parameter in a call parameter list. If 
“comma-comma’” notation is not permitted, you can code a minus one ( -1 
) to indicate the missing parameter. For example: 


(parameter ,-1, parameter2,~1) 


For languages which do not permit missing parameters and which pass all 
parameters by reference, missing integer parameters are indicated by passing 
a reference to a binary integer whose value is - |. Optional address param- 
eters (such as the address of the indicator variable in ODEFIN) must be 
passed by value as a -1. If a compiler does not permit parameters to be 
passed by value, then all address parameters are mandatory. Ifa compiler 
permits optional trailing parameters, then no trailing commas are necessary. 
Languages such as C permit neither optional parameters, nor missing trail- 
ing parameters, 


Using Substitution Variables 
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When SQL is used within a programming language, substitution variables 
may be used within the SQL statement. Substitution variables allow pro- 
grams to dynamically modify SQL statements, which can then be re- 
executed with new values. 














SQL substitution variables are identified by a colon. Substitution variables 
may be used anywhere in a SQL statement that a constant may be used. 
For example, the following OSQL3 call (written in C) uses one substitution 
variable (DEPT) for which any actual department number can be substi- 
tuted: 


osq13 (CURL, 'SELECT ENAME,SAL FROM EMP WHERE DEPTNO = :DEPT'); 


The OBNDRV or OBNDRN call is then used to substitute actual values 
for substitution variables: 


obndrv(CURI, ":DEPT",5,DEPT,2,3,1, short *(-1), 
char *(1),0,-1); 
(where DEPT is a variable defined in the user program as a 2-byte fixed 
point number.) 


SQL substitution variables are also used to bind values in INSERT and 
UPDATE statements. The following example inserts the values bound for 
substitution variables (:A, :B, :C) into the respective fields (DEPTNO, 
DNAME, and LOC), and a null is inserted into EMPCNT: 


osq13 (CUR2, "INSERT INTO DEPT 
(DEPTNO, DNAME, LOC,EMPCNT) VALUES 
(:A,:B,:C,NULL)",-1); 


Null values may be inserted into the database by specifying NULL in the 
INSERT list or by binding a value with a zero length indicator variable to 
a SQL substitution variable: 

obndrv(CUR2,":C",2,LOC,14,1,1,0); 
See also the description of the OBNDRYV and OBNDRN calls. 
An example of how to specify OSQL3 is given in Chapter 9. 


Using Indicator Variables 





Indicator variables are used in both binds and defines of host variables. 


When used in the OBNDRV or OBNDRN calls, an indicator variable can 
be used to bind ina NULL. If ’indp” points to a negative short integer 
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Note on Using Compiler 
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Since character fields may be blank padded, “progvarl” should specify the 
maximum number of characters to be bound given that trailing blanks will 
be removed by Pro*SQL. 


When used in the ODEFIN call, an indicator variable can indicate whether 
the field fetched was NULL, truncated, or not altered, by returning one of 
the following: 


tsize= 10. 
negative The field fetched was NULL. 


zero The field fetched was the same length or shorter than the program 
buffer provided. 


positive The field fetched was a greater length than was provided by the 
program buffer and the positive value returned by the indicator 
variable is the actual length of the field before truncation. 


Optimizers 


Many language compilers optionally optimize the generated code in such a 
way that program variable addresses do not accurately reflect the location 
of a variable in storage at all times. For example, optimizers will frequently 
place commonly used variables in registers, and only store them in memory 
locations when they are referenced in a subroutine call. 


When the address of a variable to be used later (such as buffer addresses in 
the ODEFIN and OBNDRV/OBNDRN calls) is passed to ORACLE as 
a parameter, the programmer must insure that the addressed variable is ac- 
tually at the specified location when it is used in a subsequent OFETCH 
or OEXEC call. 


The easiest way to insure the accuracy of variable addresses is to disable the 
compiler optimizer. 





CHAPTER 9. INDIVIDUAL PROGRAM CALL DESCRIPTIONS 








This chapter introduces each OCI call. A section for each call shows its 
general syntax, includes a discussion of its use and parameters, and gives 
examples in the languages FORTRAN, COBOL, and C. Calls are dis- 
cussed in the general order they might appear in a program, not alphabet- 
ically. (Note that a call summary showing calls in alphabetical order can 
be found in Appendix D.) 
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THE OLON CALL 








L CALL OLON ( Ida [,uid, uidlen] [,psw, pswi] [,audit_flag] 5] 
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The OLON call establishes communication between ORACLE and a user 
program. 


Communication takes place via the logon data area (LDA) defined within 
the user program. The OLON call connects the LDA to ORACLE. 


A program can log on to ORACLE multiple times, but only one OLON 
call and username can be active at one time. To switch to another 
username using the same LDA, you must code an OLOGOF, then another 
OLON with another username. To switch to a second user with a second 
LDA, you can use the ORLON call. A program has one and only one 
LDA at a time. 


After a OLON call is executed, if a OLOGOF call is executed, then all 
outstanding transactions are committed. If a user program fails to logoff 
or terminates abnormally, outstanding transactions are rolled back. 


The LDA is a 64-byte data area defined within the user program. The first 
short binary integer of the LDA contains a return code indicating the result 
of the OLON call. A zero return code indicates a successful logon. Error 
return codes are listed in the ORACLE Error Messages and Codes Manual. 


Ida (address) specifies the address of the 64-byte logon data area defined 
within the user program. 


uid (address) specifies the address of a character string containing the 
username and possibly the password. If the user password is in- 
cluded as part of the uid, it must be separated from the username 
bya“/’. 


uidlen (binary integer) specifies the length of the uid string. If the uid is a 
null terminated character string, then this parameter may be 
omitted. 


psw (address) specifies the address of the password. If the password is _ 
specified as part of the uid parameter, then the psw parameter is 
not required. 


pswl (binary integer) specifies the length of the password. If the psw is a 
null terminated character string, this parameter may be omitted. 


audit_flag (binary integer) is not supported; the only permissable value is 
a binary integer 0 (zero). 











OLON Example 








olon(Ida,uid,-1,(char *)~1, 


wife, psor 


0); i 


adi 


al 
gad 
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THE ORLON CALL 














L CALL ORLON ( Ida, hda [,uid, uidlen] [, psw, pswl] [,audit_flag] ) | 
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A program can log on to ORACLE multiple times. The ORLON call es- 
tablishes concurrent communications between ORACLE and a user pro- 
gram. 


Communication takes place via the logon data area (LDA) and the host 
data area (TIDA) defined within the user program, The ORLON call con- 
nects the LDA to ORACLE. 


'Fhe host data area is a 256-byte data arca associated with each login per- 
formed using the ORLON call. Its contents are entirely private to 
ORACLE but the HDA must be allocated by the user program, just like 
the logon data area and cursor data area. Hach concurrent login requires 
one LDA-IDA pair. 


After a ORLON call is executed, if a OLOGOP call is executed, then all 
outstanding transactions are committed. If a user program fails to logoff 
or terminates abnormally, outstanding transactions are rolled back. 


The LDA is a 64-byte data area defined within the user program. The first 
short binary integer of the LDA contains a return code indicating the result 
of the OLON call. A zero return code indicates a successful logon. Error 
return codes are listed in the ORACLE Error Messages and Codes Manual. 


Ida (address) specifics the address of the 64 byte logon data area defined 
within the user program. 


hda (address) specifics the address of the 256-byte host data arca. 


uid (address) specifies the address of a character string containing the 
username and possibly the password. If the user password is in- 
cluded as part of the uid, it must be separated from the username 
by a “7”. 


uidlen (binary integer) specifies the length of the uid string. If the vid is a 
null terminated character string, then this parameter may be 
omitted. 


psw (address) specifics the address of the password If the password is spec- 
ified as part of the uid parameter, then the psw parameter is not 
required. 


pswl (binary integer) specifies the length of the password. If the psw is a 
null terminated character string, this parameter may be omitted. 








pswi (binary integer) specifies the length of the password. If the psw is a 
null terminated character string, this parameter may be omitted. 


audit_flag (binary integer) is not supported; the only permissable value is 
a binary integer 0 (zero). 
You should also refer to the section on ORACLE*Net in the installation 


and user's guide for your operating system for any particular notes or re- 
strictions which may apply for your operating systern. 





ORLON Example 





orlon(ida,uid,-1,(char *)-1,-1,0); 
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THE OOPEN CALL 








i CALL OOPEN (cursor, Ida, [dbn, dbnlen] [,areasize] [,uid, uidlen] ) 





The OOPEN call establishes a cursor to pass a SQL statement from a user 
program to ORACLE. 


A cursor is a data area defined within the user program. The OOPEN 
connects a given cursor to ORACLE. When an OSQL3 call is used to as- 
sociate a SQL statement with a cursor, the cursor name identifies an active 
SQL statement within the user program. 


A cursor may control only one SQL statement at a time. The same cursor 
may be reused to control another SQL statement by first calling OSQL3 
again with a different SQL statement. 


A single user program can have multiple SQL statements (multiple cursors) 
active at the same time. This is accomplished by issuing multiple OOPENs 
to establish multiple cursors within the program. 


The cursor data area contains status information on an active SQL opera- 
tion. All subsequent ORACLE calls referencing a SQL statement reference 
it by cursor name. The first two bytes of the cursor contain a return code 
indicating the result of the OOPEN. A zero return code indicates a suc- 
cessful OOPEN call. Error return codes are listed in the ORACLE Error 
Messages and Codes Manual 


cursor (address) specifies the address of a 64-byte cursor data area within 
the user program. The cursor data area is connected to ORACLE 
by the OOPEN call. Each cursor defines an active SQL statement 
within the program. 


Ida (address) specifies the address of the logon data area specified in the 
OLON call. 


dbn (address) is included only for ORACLE Version 2 compatibility. It is 
not used. 


dbnlen (address) is included only for ORACLE Version 2 compatibility. 
It is not used. 


areasize (binary integer) This optional parameter is used to specify a size 
for the ORACLE SQL Work Area (SWA or context size) other 
than the default size specified by the ORACLE initialization file, 
INIT.ORA. If the size is between 1 and 128, then it is taken to 
be in increments of 1024 bytes. Ifthe size is greater than 128, then 
the size is taken to be in increments of 1 byte. The SWA must 
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be large enough to contain the compiled SQL statement plus one 
row of data of the table or view being processed. The maximum 
value for areasize is dependent on the operating system on which 
ORACLE is running. See the ORACLE Installation and User's 
Guide for your operating system for more information. The 
minimum work area is 3072 (3K) bytes. See the chapter on 
“Program Interface Data Areas” for a further description of 
ORACLE SQL Work Areas. 


uid (address) specifies the address of a character string containing the 


username and the password, The user password must be sepa- 
rated from the username by a ”/”. 


If the connection to ORACLE was established using the Version 
2 OLOGON call, then the username is used in the OOPEN call. 
If the OLON call was used, the uid and uidlen parameters are ig- 
nored in the OOPEN call. 


uidlen (binary integer) specifies the length of the uid string. Ifthe uid is a 


null terminated character string, then this parameter may be 
omitted. ` 








OOPEN Example 





oopen( 1da, curs, (char *)-1,~-1,~1,(char *)-1,-1); 
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THE OSQL3 CALL 








CALL OSQL3 (cursor, sqlstatement [,sqllen] } 


The OSQL3 call associates a SQL statement with an open cursor and. 
passes that SQL statement to ORACLE. Subsequent calls reference the 
SQL statement by cursor name. A cursor may be serially reused by sub- 
sequent OSQL3 calls within a user program or the program may define 
multiple concurrent cursors. 





The SQL statement may be any valid SQL query, data manipulation, data 
definition, or data control statement. ORACLE parses the statement and 
selects an optimal access path to perform the requested function. However, 
the operation is not executed until the OEXEC call. 


SQL syntax error codes are returned in the return code of the cursor data 
area and the parse error offset pointer to the error in the SQL statement 
text. See the description of the cursor data area for a list of the information 
fields available in the cursor data area after an OSQL3 call. Error return 
codes are listed in the ORACLE Error Messages and Codes Manual 


cursor (address) specifies the address of a 64-byte data area within the user 
program, The cursor data area contains status information on an 
active SQL operation. Each cursor defines an open SQL state- 
ment within the user program. 


sqistatement (address) specifies the address of a character string containing 
any valid SQL statement. The SQL statement may contain sub- 
stitution variables anywhere a constant is permitted. Substitution 
variables are identified by preceding the variable name with a co- 
lon (:), Le. SEMPNO. The substitution variables then may be 
referenced symbolically in an OBNDRN or OBNDRY call. 


sqllen (binary integer) specifies the length of the SQL statement. If the 
SQL statement is a null terminated character string, this parameter 
may be omitted. 





OSQL3 Example 
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if (osqi3(curs,"SELECT ENAME,JOB FROM EMP",~1) 








THE ODSC CALL 





| i CALL ODSC (cursor, position [,dbsize] [,fsize] [,rcode] [,dbtype] 








[,cbuf, [cbufl]] [,dsize]) 





| The ODSC call is used primarily for SQL queries (SELECT statements). 
It returns internal datatype and size information for a field or expression in 
the select-list of a query. 


ODSC operates positionally, one field at a time, referencing each field in the 
select-list as if each were numbered consecutively, left to right, beginning 
with 1. 


ODSC can be used after a OSQL, OEXEC, or OFLTCH call to determine 
the maximum size, internal datatype (dbsize and dbtype), and column 
names of fields to be returned as the result of a query. If ODSC is used 
after an OFETCH, the actual size of the field just fetched (fsize) may also 
be returned. 


If the user specifies a position number greater than the number of fields in 
the select-list, ODSC returns an end-of-fetch indicator in the return code 
field of the cursor data area, ODSC allows programs to dynamically de- 
termine the number of fields to be returned as the result of a query, which 
is necessary if the program does not know in advance how many fields there 
are in the select-list, as in the case of SELECT *, 


cursor (address) specifies the address of a 64-byte data area within the user 
program. ODSC uses the cursor name to reference a specific SQL 
query statement which has been passed to ORACLE in a prior 
OSQL call. The return code field of the cursor data arca indicates 
success (zero) or failure (non-zero) of the ODSC call. Error re- 
turn codes are listed in the ORACLE Error Messages and Codes 
Manual. 


position (binary integer) specifies the position of a field or expression in the 
select-list of a SQL query. Fields and expressions in a select-list 
are separated by commas. Hach field or expression is referenced 
positionally as if the fields were numbered left to right consec- 
utively beginning with 1. If the user specifies a position number 
greater than the number of fields in the select-list, ODSC returns 
an end-of-fetch indicator in the return code field of the cursor data 

| area. 





dbsize (address) specifies the address of a short binary integer which will 
receive the maximum size of the ficld, as stored in the Data Dic- 
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tionary. If the field is defined as CHAR or NUMBER, the length 
returned is the maximum length specified for the field. 


fsize (address) This field is valid only if the ODSC is issued after a 
OFETCH call. It specifies the address of a short binary integer 
which will receive the actual size of the data value returned by the 
last OFETCH operation. The value returned is the actual length 
of the value as stored in the database before it is moved to the user 
buffer where padding or truncation may take place. ORACLE 
suppresses leading zeros on numeric data and trailing blanks on 
character data before storing the values in the database. 


rcode (address) specifies the address of a short binary integer which will re- 
ceive the column return code returned by the last fetch operation. 
This parameter is valid only if the ODS is issued after a OFETCH 
call. 


dbtype (address) specifies the address of a short binary integer which will - 
receive the internal datatype of the field as it is stored in the Data 
Dictionary. Fields defined as CHAR are stored as variable length 
strings and return a value of 1. Fields defined as NUMBER are 
stored in ORACLE internal scaled integer fields and return a value 
of 2. Fields that contain expression results also return a value of 
2. Fields defined as DATE are stored as 
YYYYMMDDHHMMSS strings and return a value of 12. 


cbuf (address) specifies the address of a data field buffer within the user 
program which will receive the name of the column or expression. 
If cbuf is 0, then the column name is not be stored. 


cbufl (address) specifies the address of a short binary integer which contains 
the length of cbuf. If the column name to be stored is longer than 
cbufl, then the column name is truncated. When ODSC is exe- 
cuted, cbufl receives a short binary integer which is the length of 
the column name stored in cbuf. If cbufl is not specified, or if the 
value contained in cbufl is 0, then the column name is not stored. 


dsize (address) specifies the address of a short binary integer which will re- 
ceive the maximum display size of the field when it is returned as 
a character string, dsize is especially useful when functions, like 
SUBSTR or TO_CHAR, are used to modify the representation 
of a column. 





SASS neu OU 





ODSC Example 





odsc(curs,1,&deptl, (short *)01, (short *)01, 
(short *)01,(char *)-1,(short *)~1,(short *)~1); 
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THE ONAME CALL 








CALL ONAME (cursor, position, tbuf, tbufl, cbuf, cbufl) | 
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The ONAME call is used to retrieve the names of the columns in a select- 
list of a SQL query. ONAME operates positionally on one field at a time, 
referencing each field or expression in a select-list as if each were numbered 
sequentially from left to right, beginning with 1. 


ONAME may be used after a SQL call to determine the column or ex- 
pression name string of fields to be returned. The maximum length of a 
column name literal expression text is 240 bytes. 


If you specify a position number greater than the number of fields in the 
select-list, ONAME returns an end-of-select-list indicator in the return code 
field of the cursor data area. Programs can use the end-of-select-list status 
to dynamically determine the names of fields to be returned as the result 
of a query for which the number of fields is unknown, as in the case of 
SELECT *. 


cursor (address) specifies the address of a 64-byte data area within the user 
program. The ONAME call references the cursor name to asso- 
ciate a data field buffer with a specific SQL, statement. 


position (binary integer) specifies the position of a field or expression in the 
select-list of a SQL query. Fields are separated by commas and 
numbered left to right consecutively, beginning with 1. If the user 
specifies a position number greater than the number of fields in 
the select-list, ONAME returns an end-of-fetch indicator in the 
return code field of the cursor data area. ONAME uses the posi- 
tion number to relate buffers to ficlds in the select-list. 


tbuf (address) is included only for ORACLE Version 2 compatibility. It is 
not used. 


tbufl (address) is included only for ORACLE Version 2 compatibility. It 
is not used. 


cbuf (address) specifies the address of a data field buffer within the user 
program which will receive the name of the column or expression. 
If cbuf is zero, then the column name is not stored. 


cbufl (address) specifies the address of a short binary integer which contains 
the length of cbuf. If the column name to be stored is longer than 
cbufl, then the column name is truncated. After ONAME is ex- 
ecuted, cbufl contains a short binary integer which is the length 











of the column name stored in cbuf. If cbufl not specified, or if the 
value contained in cbufl is 0, then the column name is not stored. 





ONAME Example 








oname(curs[1],2,&table, &tablen,&col,&col] en): | 
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THE ODEFIN CALL 








CALL ODEFIN (cursor, pos, buffer, bufl, ftype [,scale] [, indp] 
[fmt], fmt] [,fmtt } ] [,ret?] [,rcode] ) 








The ODEFIN call defines one output buffer for each field in a select-list in 
a SQL query. ODEFIN defines one data field buffer at a time. Buffers are 
defined after the OSQL call and prior to the OFETCH call. 


ODEFIN specifies the location and size of a data field buffer in the user 
program. ODEFIN also passes the external datatype of the field as defined 
by the user program and optionally specifies a field return code. 


Select buffers are always defined positionally. Fields in the select-list are 
referenced as if they were numbered consecutively, left to right, beginning 
with 1. During an OFETCH, ORACLE converts each field from internal 
to the specified external datatype and then stores the fields in the defined 
buffers. 


ORACLE provides return code information at the row level, via the return 
code field in the cursor data area, and optionally at the field level, via the 
ODEFIN field return code. During each OFETCH, ORACLE sets a re- 
turn code for each field processed. This code indicates either successful 
completion (0) or an exceptional condition such as null field fetched, field 
truncated, or other non-fatal column errors. The field return code is stored 
in the rcode variable for each defined field. Field level return codes are de- 
scribed in the ORACLE Error Messages and Codes Manual. 


cursor (address) specifies the address of a 64-byte data area within the user 
program, The ODEFIN call references the cursor name to asso- 
ciate a data field buffer with a specific SQL statement. 


pos (binary integer) specifies the position of a field or expression in the 
select-list of a SQL query. Fields are separated by commas and 
numbered left to right consecutively, beginning with 1. Ifthe user 
specifies a position number greater than the number of fields in 
the select-list, ODEFIN returns an end-of-file indicator in the re- 
turn code field of the cursor data area. ODEFIN uses the position 
number to relate buffers to fields in the select-list. 


buffer (address) specifies the address of the data field buffer within the user 
program which will receive data when OF ETCH is executed. 


bufl (binary integer) specifies the length of the buffer being defined. 


ftype (binary integer) specifies the external datatype that the field is to be 
converted to before it is moved to the user buffer. A list of the 
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| 

external datatypes and type codes is contained in the chapter on 
datatypes. 


scale (binary integer) specifies the number of fractional digits to the right 
of the decimal point to be returned for fields of ftype 7 (COBOL 
packed decimal). scale is ignored for all other datatypes. 


indp (address) specifies the address of a short binary integer which will re- 
ceive the length of a fetched field. 


| 

| 

| 

| 

| When used in the ODEFIN call, an indicator variable can indicate 
l whether the field fetched was NULL, truncated, or not altered, 

| by returning one of the following: 


negative The field fetched was NULL. 


zero The field fetched was the same length or shorter than the 
program buffer provided. 


positive The field fetched was a greater length than was provided 
by the program buffer and so was truncated. The posi- 
tive value returned by the indicator variable is the actual 
length of the field before truncation. 


fint (address) specifies the address of the conversion format string. Cur- 
rently it can only be used with the ftype of 7, COBOL packed 
decimal. The format for the string is “mm.[+ /-]nn”, where “mm” 
is the total number of digits, from 1 to a maximum of 38, and 
“nn” is the number of decimal places or scale (for example, 
09.+02). The plus or minus sign is required. If ”+” is specified, 
then “nn” is the number of the digits to the right of the decimal 
place. If ”-” is specified, then “nn” is the power of ten by which 
to multiply the number before placing it in the program buffer. 
Future implementations may allow for additional formatting. If 
your compiler does not allow for optional parameters or for 
passing an address parameter as a value of ”-1”, then use the length 
parameter fmti with a value of 0 to indicate that there is no fmt 
to be specified. 


fmtl (binary integer) specifies the length of the fmt conversion format 
string. if the value of fmtl is 0, then fmt and fmtt are not used, 





l fmtt (binary integer) specifies the format type of the conversion format 
| string. Currently only 7 (COBOL, packed decimal) is allowed. 
| All other values are ignored. 


| retl (address) specifies the address of a short binary integer where ORACLE 
places the actual length of the returned column. Return lengths 
are filled in after an OFETCH operation. 
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reode (address) specifies the address of a short binary integer which will re- 
ceive a field return code after a OFETCH operation. The fol- 
lowing codes are some error messages that are reported for field 
errors. 


CODE MEANING 
0 success 


1406 = ASCII or string buffer data was truncated. The con- 
verted data from the database did not fit into the buffer. 


1454 invalid conversion specified: integers not of length 1,2, 
or 4; reals not of length 4 or 8; invalid packed decimal 
conversions; packed decimal with more than 38 digits 
specified. 


1455 real number overflow. Conversion of a database field 
would result in a real number whose magnitude was 
greater than the real number (floating point) machine 
format. 


1456 integer overflow. Conversion of a database field would 
result in an integer which would have lost significant 
digits if moved to a machine integer of the size specified. 


1457 decimal overflow. Conversion of a database field would 
result in loss of significance if placed in the specified 
packed decimal field. 


3004 the conversion requested is not supported, Not used for 
S. 


ODEFIN Example 


odefin(curs,1,&empno,2,3,-1,(short *)-1,(char *)-1, 
-1,-1,&rlen,&rcode); 














THE OBNDRV AND OBNDRN CALLS 








CALL OBNDRV (cursor, sqlvar, sq]v1, progvar, progv], ftype[, scale][, indp] 
CL, fmt, fmt1]], fmtt]]) 
CALL OBNDRN (cursor, sqlvarnum, progvar, progv1, ftype[ ,scale][, indp] 
-E fmt, fmt1]], fmtt]]) 





The bind calls OBNDRV and OBNDRN are used to dynamically modify 
a SOL statement after it has been passed to ORACLE in a OSQL3 call. 
For example, you may wish to change the values used in a WHERE clause, 
such as DEPTNO, to change the set of rows fetched. A SQL statement 
may be executed, modified using OBNDRV or OBNDRN, and re-executed 
as desired, 


The OBNDRV and OBNDRN calls specify that a program value is to be 
assigned to a SQL substitution variable within a SQL statement. Tf used, 
both calls should be called once for each program variable before the 
OEXEC call. Once called, the address of the program variable is kept by 
ORACLE. These bind calls do not need to be called again when the pro- 
gram variable changes. Because of this reference to an absolute memory 
location, the progvar and progy! parameters must be constantly mapped in 
memory. ORACLE does not remap. If you change the actual variable 
used (versus its value), the bind must be called again with the new variable 
names, 


OBNDRV and OBNDRN are exactly the same except in the way they 
reference SQL substitution variables. OBNDRN references SQL substi- 
tution variables numerically. OBNDRYV references SQL substitution vari- 
ables symbolically by name. The name of the variable to be bound must 
not be an ORACLE reserved word. 


At the time of the bind, ORACLE converts the program variable from 
external to internal format, and then moves the data value into the SQL 
statement. OBNDRV and OBNDRN are used after the OSQL3 call and 
prior to the OBXIC call. If the same substitution variable name occurs 
more than once, a single call to OBNDRV or OBNDRN will bind them 
all. The number of variables bound is returned in the Parse Error Offset 
field of the cursor data area. 


The completion status of the bind is indicated in the return code field of the 
cursor data area. Error return codes are listed in the ORACLE Error Mes- 
sages and Codes Manual. If a character to numeric conversion error 
(ORACLE error + 5) occurs, binding will stop and the Return Code will 
contain +5. Ifan ORACLE error which has a negative value (such as 
-625, non-supported conversion) occurs, binding will stop and the Parse 
Error Offset field will indicate the variable name occurrence number where 
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the error occurred. If the substitution name does not exist, the ORACLE 
error -605 is returned. 


cursor (address) specifies the name of a 64 byte data area within the user 
program. OBNDRYV and OBNDRN use the cursor name to ref- 
erence a specific SQL statement. 


sqlvar (address) Used only with OBNDRYV, specifies the address of a char- 
acter string containin the name of a substitution variable within 
the SQL statement. The variable name is preceded by a colon (:) 
in the SQL statement, i.e. WHERE EMPNO = ‘EMPLOYEE. 
OBNDRV moves the program variable value into the SQL sub- 
stitution variable :EMPLOYEE. 


sqlvl (binary integer) Used only with OBNDRYV, specifies the length of the 
character string specified for sqlvar. For example, ‘EMPLOYEE 
has a length of 9. If the substitution variable is a null terminated 
character string, this parameter may be omitted. 


sqlvarnum (binary integer) Used only with OBNDRN, specifies the num- 
ber of a SQL substitution variable within the SQL statement ref- 
erenced by the cursor. For example, if sqlvarnum contains the 
value 2, it references a SQL substitution variable defined as :2. 


progvar (address) specifies the address of a variable defined within the user 
program from which data will be retrieved when OR XEC is exe- 
cuted. The address of the program variable is kept by ORACLE 
at the time of the bind. 


progvl (binary integer) specifies the length of the program variable. Since 
these calls are referenced only once, this length field must contain 
the maximum length of progvar, the program variable field. In 
order to bind a NULL value to a program variable, use the indp 
field. 


fiype (binary integer) specifies the datatype of the program variable as de- 
fined within the user program. ORACLE converts the program 
variable from external to internal format before it is bound to the 
SQL statement. A list of external datatypes and type codes is 
contained in the chapter on datatypes. 


scale (binary integer) specifies the number of fractional digites to the right 
of the decimal point for fields of ftype 7 (COBOL packed deci- 
mal). This value is ignored for all other datatypes. 


indp (address) specifies the address of a short binary integer that indicates 
whether or not the column value is to be bound as a NULL. If 
“indp” points to a negative short integer when OEXEC is called, 





then the column is bound as a NULL; otherwise, the value 
pointed to by “progvar” with a length of “progvarl” is bound. 


fmt (address) specifies the address of the conversion format string. Cur- 


rently it can only be used with the ftype of 7, COBOL packed 
decimal. The format for the string is “mm.[+ /-]nn”, where “mm 
is the total number of digits, from 1 to a maximum of 38, and 
“nn” is the number of decimal places or scale (for example 

09.+ 02). The plus or minus sign is required. If ’-+” is specified, 
then “nn” is the number of the digits to the right of the decimal 
place. If ’-” is specified, then “nn” is the power of ten by which 
to multiply the number before placing it in the program buffer. 
Future implementations may allow for additional formatting. If 
the compiler in use does not allow for optional parameters or for 
passing an address parameter as a value of ”-1”, then use the length 
parameter fmtl with a value of 0 to indicate that there is no fmt 
to be specified. 


” 


fmtl (binary integer) specifies the length of the fmt conversion format 


string. Ifthe value of fmt is zero, then fmt, and fmtt are not used. 


fmtt (binary integer) specifies the format type of the conversion format 


string. Currently only 7 (COBOL packed decimal) is allowed. 
All other values are ignored, 
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OBNDRV Example 








obndrv (curs,":ENAME",-1,strings,~1,1,-1,(short *)-1, 
(char *)-1,0,0); 
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THE OOPT CALL 








CALL OOPT (cursor, rollbackopt, waitopt) 





The OOPT call is used to set: 


e rollback options for non-fatal ORACLE errors involving multi-row 
INSERT and UPDATE SQL statements 


e wait options for when requested resources are not available -- for ex- 
ample, whether to wait for row level locks or other locks. 


cursor (address) specifies the address of a 64-byte data area within the user 
program. 


rollbackopt (binary integer) specifies the action 10 be taken when a non- 
fatal ORACLE error occurs. If this option is set to 0, all errors, 
even non-fatal errors, cause the current transaction to be rolled 
back. If this option is set to 2, only the failing row will be rolled 
back during a non-fatal row-level error. This is the default setting. 
The FLAG2 bits in the cursor data area indicate whether a failure 
was fatal or not. 


waitopt (binary integer) specifies whether to wait. for resources or continue. 
If this option is set to 0, the program waits indefinitely if resources 
are not available. This is the default. If this option is set to 4, the 
program will receive an error return code whenever a resource is 
requested but is not available. Use of waitopt set to 4 may cause 
many error return codes while waiting for internal resources which 
are locked for short durations. The only resource errors received 
are for resources requested by the calling process. 


OOPT Example 


oopt(curs, 2,4) 
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THE OEXEC CALL 





CALL OEXEC (cursor) 





The OEXEC call causes the SQL statement currently associated with a 
cursor to be processed. 


The OEXEC call must be preceded by a successful OSQL3 or OSQL call. 
If the SQL statement is a query, each column or expression in the select-list 
must have a program variable associated with it before the OEXEC call. 

If the SQL statement has program variables embedded, then they must have 
values bound to them before the OEXEC call. Data to be bound using the 
OBNDRV and OBNDRN calls is moved to ORACLE when OEXEC is 
called. Then, the user program must explicitly request each row of the re- 
sult using the OFETCH call. 


If the SQL statement is a data manipulation, data definition, or data control 
statement, the entire SQL function is performed at this time; the return 
code field in the cursor data area is set and a count of the rows processed 
by the statement is placed in row count field of the cursor data area. 


If a single row is rejected due to an error and OOPT is set to 2, the rejected. 
row is rolled back and none of the other rows are rolled back. If OOPT is 
set to 0, the entire transaction is rolled back. 


cursor (address) specifies the address of a 64-byte data area within the user 
program. 
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OEXEC Example 


oexec(curs); 





——————— 





THE OEXN CALL 








C CALL OBXN (cursor, count, offset) | 
where: 
cursor (address) specifies the address of a 64-byte data within the user pro- 
gram. 


i 

i 

| 

| 

| count (binary integer) specifies the size of the bind variable array on which 
| to operate. 
| 


offset (binary integer) specifies the offset withing the bind variable array at 
which to begin operations. 


OEXN allows operations using an array of bind variables. Its operation is 
similar to OBXEC which allows operations on a single set of bind variables. 
Bach substitution variable declared using OBNDRV or OBNDRN is the 
first element of an array of variables. For example, this C program seg- 
ment: 


int progvari[10]; 

char progvar2[10][50]; 

OSQL3 (cursor, "INSERT INTO TBL1 VALUES (:VARI, :VAR2)", -1); 
OBNDRV (cursor, ":varl", ~1, progvarl[0], 4, 3, ... ); 
OBNDRV (cursor, ":var2", -1, progvar2[0], 50, 1, ... ); 


declares two arrays, one of 10 integers, and one of ten 50-character strings, 
and issues a SQL, statement which can be used to insert multiple rows into 
the database. This gives a user two ways to insert data: he can insert one 
row at a time using OEXEC (cursor), and insure that the data is always 
placed in progvar![0] and progvar2(0], or he can insert up to 10 rows at a 
time using OEXN (cursor, 10, 0). He then places the values for the first 
row into progvar] [0] and progvar2[0], the values for the second row into 
progvar [1] and progvar2[1], etc. 





The completion status of OEXN is indicated in the Return Code field of 
the cursor data area. The rows process count in the cursor data area indi- 
cates the number of rows successfully processed. If it is not equal to 
“count”, then the operation failed on array element count + 1, ‘The user 
may continue to operate as long as a rollback did not occur (see flags! in 
the cursor data area description), by using “offsct” to start operations at 

| array elements other than the first, and adjusting the count appropriately. 

| In the above example, if the rows processed count. was 5 at completion of 
OEXN, then row 6 was rejected. To continue the operation at row 7, issue: 
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OEXN (cursor, 3, 7); /* operation on 3 array elements 
starting at the seventh 
(progvarl1[6], prog2var[6]) */ 
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THE ORES CALL 








CALL ORES (cursor) | 





The ORES call is no longer supported. 
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THE OFETCH CALL 





CALL OFETCH (cursor) 





The OFETCH call returns rows of a query result to the user program, one 
row at a time. Each field of the query is placed into a buffer identified by 

a previously executed ODEFIN call. Fields that are requested by the user 
program in character string format are left-justified and padded with trailing 
blanks. Character strings that are too large for the field buffer are truncated 
and both the field return code and the cursor return code are set to + 3. 


If null values are encountered in any field of the fetch, the ORACLE field 
return code for that field is set to +2 and the user buffer rernains un- 
changed. To determine which specific fields are null or have been trun- 
cated, the user program must have specified either field return codes or 
indicator variables in the ODEFIN buffer calls or may issue a ODSC call 
after the OFETCH call. 


The cursor maintains position on a set of rows that satisfy a query as those 
rows are retrieved, one at a time, by the OFETCH call. After each 
OFETCH the row count field in the cursor data area is updated. The rows 
are retrieved sequentially. There is no way to recall rows previously fetched 
except by re-executing the OEXEC call and moving forward. again. After 
the last row of the query result has been returned to the user program, the 
next fetch will return an end-of-file return code of +4. When end-of-file 
has been reached, the Row Count field contains the total number of rows 
found by the query. 


cursor (address) specifies the address of a 64-byte data area within the user 
program. 


OFETCH Example 









ofetch(curs); 
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THE OFEN CALL 











CALL OFEN (cursor, count) 





where: 


cursor (address) specifies the address of a 64-byte data within the user pro- 
gram. 


count (binary integer) specifies the size of the define variable array on which 
to operate. 


OFEN allows programs to fetch multiple rows into an array of define var- 
iable with a single call. It is similar to the OFETCH call which fetches a 

single row. Each define variable declared using ODEFIN or ODFINN is 

the first element of an array of variables. For example, the following pro- 
gram segment: 


int progvarl[10]; 

char progvar2[10][50]; 

OSQL3 (cursor, "SELECT VARI, VAR2 TBL1",-1); 
ODEFIN (cursor, 1, progvari[0], 4, 3, ... ); 
ODEFIN (cursor, 1, progvar2[0], 50, 1, ... ); 


declares two arrays, one of 10 integers, and one of ten 50-character strings, 
and issues a SQL statement which can be used to fetch multiple rows from 
the database. The user now has two ways to fetch the data: he can fetch 
one row at a time using OFETCH (cursor), and insure the data will always 
be placed in progvar1[0] and progvar2[0], or he can fetch up to 10 rows at 
a time using OFEN (cursor, 10). The data for the first row is placed into 
progvar]{0] and progvar2{0], the values for the second row into progvar [1] 
and progvar2[1], etc. 


The completion status of OFEN is indicated in the return code field of the 
cursor data area. The rows processed count in the cursor data area indicates 
the number of rows successfully processed since the OEXEC call was issued 
(that is, the count is cumulative). If the rows process count is not increased 
by the requested COUNT, then an error has occurred, such as END OF 
FETCH. The operation may be continued if more rows can be returned, 
and it must be continued using the first array element. 
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THE OBREAK CALL 





CALL OBREAK (1da) 





The OBREAK call is used to asynchronously abort an ORACLE function 
which is in progress. Its primary use is to stop a long running OEXEC or 
OFETCH call which has not yet complete. It will, however, stop any 
ORACLE function which is in progress. OBREAK terminates whatever 
operation is in progresson the host ORACLE associated with the LDA 
specified. 


If no ORACLE function is active when OBREAK is called, it will be ig- 
nored unless the next ORACLE function called is OFETCH. 


OBREAK is the only ORACLE call allowed when another ORACLE 
function is in progress. It may not be used when any ORACLE logon call 
(OLON, ORLON, OLOGON) is running, since the LDA is in an indeter- 
minate state. 


No error status can be returned from the OBREAK call in the LDA, since 
it may be called when the ORACLE internal status structures are in an in- 
consistent state. If the host language supports function return values, as C 
and FORTRAN do, then OBREAK wil return ORACLE error codes as 

the function return value. 


Ida (address) specifies the address of the logon data area specified in the 
OLON or ORLON call. 
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OBREAK Example 






(obreak(1da); 











THE OCAN CALL 








CALL OCAN (lda) 





The OCAN call informs ORACLE that the operation in progress for the 
specified cursor is complete. 


For example, if a cursor is used to parse a SQL statement which will return 
an indeterminate number of rows, but only the first row is needed, then 
after OEXEC and the first OFETCH are performed, OCAN can be used 
to tell ORACLE that the application program will not be performing any 
additional OFETCH calls until another OEXEC call is made. 


ORACLE uses OCAN to free any resources associated with the incomplete 
operation, including before image file space. 


The OCAN call should be used anytime the application program will not 
be performing OFETCH calls until “end of fetch” (status + 4) is returned. 


cursor (address) specifies the address of the cursor data area specified in 
the OOPEN call. 





OCAN Example 





ocan( 1da); 
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THE OCOM CALL 





CALL OCOM (1da) 


The OCOM call commits the current transaction to the database. 








The current transaction is defined as starting from the OLON call or last 
OROL or OCOM call, and lasting until an OCOM, OROL or OLOGOF 
call. If the OCOM call fails, the reason is indicated in the first two bytes 
of the logon data area (LDA). 


Ida (address) specifies the address of the logon data area specified in the 
LOGON call. 


Do not confuse the OCOM call (COMMIT WORK) with the OCON call 
(equivalent to SET AUTOCOMMIT ON). 





OCOM Example 





(ocom(1da); 
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THE OROL CALL 











| CALL OROL (Ida) 








The OROL call rolls back the current transaction. 


The current transaction is the set of SQL statements since the OLON call 
or the last OCOM or OROL call. If the OROL fails, the reason is indi- 
cated in the first two bytes of the logon data area (LDA). 


Ida (address) specifies the address of the logon data area specified in the 
OLOGON call. 








OROL Example 





orol(jda); 
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THE OCON CALL 








CALL OCON (Ida) | 








The OCON call enables autocommit (automatic commit of every SQL data 
manipulation statement). By default autocommit is disabled at the start 
of an OCI program, because it is more expensive and less flexible than 
placing OCOM calls after all logical transactions. By setting autocommit 
on, every time you see a successful return code from EXEC, the transaction 
has been committed. However, you can choose to automatically commit 
transactions by issuing the OCON call. If the OCOM call fails, the reason 
is indicated in the first two bytes of the logon data area (LDA). 


Ida (address) specifies the address of the logon data area specified in the 
OLOGON call. 


Do not confuse the OCOM call (COMMIT WORK) with the OCON call 
(equivalent to SET AUTOCOMMIT ON). 








OCON Example 





ocon( lda); 
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THE OCOF CALL 


[ CALL OCOF (Ida) 


The OCOF call disables autocommit (automatic commit of every SQL data 
manipulation statement). By default, autocommit is already disabled at the 
start of a Pro*SQL program. If the OCON call is used for some special 
circumstance, the OCOF call should be used to disable autocommit as soon 
as practical. If the OCOF call fails, the reason is indicated in the first two 
bytes of the logon data area (LDA). 


Ida (address) specifies the address of the logon data area specified in the 
LOGON call. 











OCOF Example 












if (ocof(curs[0])); 
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THE OERMSG CALL 








CALL OERMSG (rcode,msgbuf) 











The OERMSG call returns the ORACLE error message tex! corresponding 
to the rcode into the message buffer. If there is no message which corre- 
sponds to the return code, then the message “Unknown ORACLE error 
code” is returned. 


rcode (short binary integer) specifies the return code for which the message 
text is to be returned. OERMSG is looking for a V2/V3 error 
code; however, negation of the V4 error code will also work. 


msgbuf (address) specifies the address of a buffer in which to place the null 
terminated error message text, which may be up to 132 characters 
long. If the message is longer than the buffer size, the message 
will be truncated. 





OERMSG Example 








oermsg(cur[0],msg); 
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THE OCMN CALL 





CALL OCMN (1da,comment-, comment1~-) 





The OCMN call is not supported. 
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THE OCLOSE CALL 








- 





CALL OCLOSE (cursor) 4 





The OCLOSE call disconnects a cursor from ORACLE and frees all re- 
sources obtained by the OOPEN, OSQL, and OEXEC calls using this 
cursor. If the OCLOSE fails, the Return Code field of the cursor data area 
contains the status indicator. Error return codes are listed in the ORACLE 
Error Messages and Codes Manual. 


cursor (address) specifies the address of a 64 byte data area within the user 
program. OCLOSE disconnects the cursor, which was opened 
using the OOPEN call, from ORACLE. 





OCLOSE Example | 





oclose(curs); 
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THE OLOGOF CALL 





L 


CALL OLOGOF (1da) 





The OLOGOF call disconnects a program from ORACLE and frees all 
ORACLE resources owned by this program. 


A commit is automatically issued on a successful OLOGOF call. All cur- 
tently opened cursors are closed at OLOGOF time as well. If a user pro- 
gram fails to successfully logoff or terminates abnormally, all outstanding 
transactions are rolled back. Ifthe OLOGOF call fails, the reason is indi- 
cated in the first two bytes of the logon data area (LDA). Error return 
codes are listed in the ORACLE Error Messages and Codes Manual. 


lda (address) specifies the address of the logon data area specified in the 
LOGON call. 





OLOGOF Example 





ologof(1da); 
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CHAPTER 10. OLD PRO*SQL(OCD CALLS 





EEE EE 


This chapter summarizes older calls, which have been replaced by those in 
Chapter 2, but are included here for completeness. A section for each call 
shows its general syntax, includes a discussion of its use and parameters, 
and gives examples in the languages FORTRAN, COBOL, and C. Calls 
are discussed in the general order they might appear in a program, not al- 
phabetically. (Note that a call summary showing calls in alphabetical order 
can be found in the appendixes.) 


The calls in this chapter have been replaced by the newer calls in the pre- 
ceding chapter. Calls in this chapter are supported as described, but lack 
some functionality that has been added in the new calls. It is highly re- 
commended that the newer calls be used in new programs. These older 
calls are included to enable programmers to understand programs written 
with these older calls. 
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OLOGON 
V 
OOPEN 


V 
ee 


V 
ODFINN 


V 
noone >OBIND 
or 
OBINON 
| 
V 
OEXE 
| 


V 
---->0FETCH 








OLOGOF 


Establish the Logon Data Area 


Open a Cursor Data Area 


Associate a SQL statement with a 
Cursor and parse the statement 


Define a program buffer area to 
store the items from the select-list 
(There must be one ODFINN call for 
each item in the list.) 


Pass the values of prograin 
variables used in the SQL statement 
to ORACLE 


Execute the current SQL statement 
in the specified Cursor 


Return one row from the ORACLE table(s) 
into the program buffer area(s) defined 
by the ODFINN call 


If not end-of-fetch: 
return to the OFETCH call to get the 
next row 
If all rows have been fetched: 
If another SQL statement: 
go to OSQL 
If another BIND variable: l 
change program variable 
go to OBIND or OBINDN i 
Else close Cursor 


Disconnect from ORACLE 


Figure 16. Query Program Logic in V2 and V3 Pro*SQL(OCI) 
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THE OLOGON CALL 








CALL OLOGON (Ida [,areacount]) 





The OLOGON call was used in ORACLE Version 2 to establish commu- 
nication between ORACLE and a user program. OLOGON has been re- 
placed by the newer call OLON. 


Communication takes place via the logon data area (LIDA) defined within 
the user program. The OLOGON call connects the LDA to ORACLE. 
A program logs on to ORACLE one and only one time. A program has 
one and only one LDA. After an OLOGON call is executed, if a logoff is 
executed, all transactions are committed. If a user program fails to logoff 
or terminates abnormally, all transactions are rolled back. 


Note that the OLOGON call is a Version 2 compatibility call and does not 
actually cause a connection to be made with ORACLE. The actual logon 
occurs during the OOPEN call. If the sequence OLOGON, OLOGOF is 
issued without any intervening OOPEN call, an error code indicating “not 
logged on” is returned. 


The LDA is a 64-byte data area defined within the user program. The first 
two bytes of the LDA contains a return code indicating the result of the 
OLOGON call. A 0 return code indicates a successful OLOGON call. 
rrot return codes are listed ia ORACLE Error Messages and Codes Man- 
ual. 


lda (address) specifies the address of the 64-byte logon data area defined 
within the user program. 


areacount (binary integer) is included only for compatibility with 
ORACLE Version 2. It is not used. 


OLOGON Example i 





ologon (Idarea, 2); 
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THE OSQL CALL 





CALL OSQL (cursor, sqlstatement [,sqllen]) | 
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The OSQL call passes a SQL statement to ORACLE and associates that 
SQL statement with an open cursor. The OSQL call is used only for 
ORACLE Version 2 syntax. It has been replaced by the newer call 
OSQL3. The two calls may be freely mixed in the same program, but the 
linking instructions differ for programs containing OSQL calls. 


Subsequent calls reference the SQL statement by cursor name. 


The OSQL call may contain any valid SQL query, data manipulation, data 
definition, or data control statement. ORACLE parses the statement and 
selects an optimal access path to perform the requested function. However, 
the operation is not executed at this time. 


A cursor may be serially reused by subsequent OSQL calls within a user 
program or the program may define multiple concurrent cursors. 


OSQL syntax error codes are returned in the return code field of the cursor 
data area along with the parse error offset field, a pointer to the text in error. 
Sce the Parse Errors chapter of the ORACLE Error Messages and Codes 
Manual for a complete list of syntax errors. 


cursor (address) specifies the address of a 64-byte data area within the user 
program. 


sqlstatement (address) specifies the address of a character string containing 
any valid SQL query, data manipulation, data definition, or data 
control statement. The statement may contain substitution vari- 
ables anywhere a constant is permitted. Substitution variables are 
identified by preceding the variable name with a colon, ie. 
‘BMPNO. The substitution variables then may be referenced 
symbolically in an OBIND, OBINDN, OBNDRY, or OBNDRN 
call. 


sqllen (binary integer) specifies the length of the SQL statement. If the 
SQL statement was specified as a null terminated character string, 
this parameter may be omitted. 











OSQL Example 





osqi(curs[1],"SELECT NVL(MAX(EMPNO) FROM EMP", ~1); 
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THE ODSRBN CALL 





CALL ODSRBN (cursor,position [,dbsize][ ,dbtype][, fsize]) 





The ODSRBN call returns internal datatype and size information for a field 
or expression in the select-list of a SQL query. The ODSRBN call has been 
replaced by the newer call ODSC. 


ODSRBN operates positionally, one field at a time, referencing each field 
in the SELECT clause as if each were numbered consecutively left to right, 
beginning with 1. 


ODSRBN is used after a OSQL, OEXEC, or OFETCH call to determine 
the maximum size and internal datatype (dbsize and dbtype) of fields to be 
returned as the result of a query. If ODSRBN is used after a OFETCH 
call, the actual size of the field just fetched (fsize) may be returned in addi- 
tion to dbsize and dbtype. 


If the user specifies a position number greater than the number of fields in 
the select-list, ODSRBN returns an end-of-fetch indicator in the return 
code field of the cursor data area. This allows programs to dynamically 
determine the number of fields to be returned as the result of a query. This 
is necessary if the program does not know in advance how many fields there 
are in the select-list, as in the case of SELECT *. 


cursor (address) specifies the address of a 64 byte data area within the user 
program. The cursor data area contains status information on an 
active SQL operation. Each cursor defines an active SQL state- 
ment within the user program. ODSRBN uses the cursor name 
to reference a specific SQL query which has been passed to 
ORACLE in a prior OSQL call. The return code field of the 
cursor data area indicates the success (zero) or failure (nonzero) 
of the ODSRBN call. Error return codes are listed. in the 
ORACLE Error Messages and Code Manual. 


position (binary integer) specifies the position of a field or expression in the 
select-list of a SQL query. Fields and expressions in a select-list 
are separated by commas, Hach field or expression is referenced 
positionally as if the fields were numbered left to right consec- 
utively, beginning with 1. If the user specifies a position number 
greater than the number of fields in the sclect-list, ODSRBN re- 
turns an end-of-fetch indicator in the Return Code ficld of the 
cursor data area. 


dbsize (address) specifies the address of a short binary integer which will 
receive the maximum size of the ficld. If the field was defined as 
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CHAR or NUMBER, the length returned is the maximum length 
specified for that field as stored in the Data Dictionary. 


dbtype (address) specifies the address of a short binary integer which will 


receive the internal datatype of the ficld as stored in the Data 
Dictionary. Fields defined as CHAR are stored as variable length 
strings and return a value of 1. Fields defined as NUMBER are 
stored in ORACLE internal scaled integer fields and return a value 
of 2. Fields that contain expression results also return a value of 
2. Fields defined as DATE are stored as 
YYYYMMDDHHMMSS strings and return a value of 12. 


fsize (address) specifies the address of a short binary integer which will re- 


ceive the actual size of the data field returned by the last 
OFETCH operation. This field is valid only if the ODSRBN is 
issued after a OFETCH call. The value returned is the actual 
length of the field as stored in the database before it is moved to 
the user buffer where padding or truncation may take place. 
ORACLE suppresses leading zeros on numeric data and trailing 
blanks on character data before storing the fields in the database. 





ODSRBN Example 





odsrbn(curs[1],1,&enamel, (short *)1,(short *)-1); 
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THE ODFINN CALL 


te 





CALL ODFINN (cursor, pos, buffer, buf I[, ftype][,rcode][, fdig]) E 
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The ODFINN call defines one output buffer for each field in the select-list 
of a SQL query. The ODFINN call has been replaced by the newer call 
ODEFIN. 


ODFINN specifies the location and size of a data field buffer in the user 
program. ODFINN also passes the external datatype of the field as defined 
by the user program and optionally specifies a field return code. ODEINN 
defines one data field buffer at a time. Buffers are defined after the SQL 
call and prior to the OFETCH call. 


SELECT buffers are defined positionally. Fields in a sclect-list are refer- 
enced as if they were numbered consecutively, left to right, beginning with 
1. During an OFETCH, ORACLE converts each field from internal to the 
specified external datatype and then store the fields in the defined buffers. 


ORACLE provides return code information at the row level, via the return 
code field in the cursor data area, and optionally at the field level, via the 
ODFINN field return code. During each OFETCH, ORACLE establishes 
a return code for each field processed. This code indicates either successful 
completion (Return Code of 0) or an exceptional condition such as null 
field fetched, field truncated, or other nonfatal column errors. The field 
return code is stored in the rcode variable for each defined field. At the 
completion of each OFETCH, the last nonzero field return code encount- 
ered is placed in the return code field of the cursor data area. 


cursor (address) specifies the address of a 64 byte-data area within the user 
program. The ODFINN call references the cursor name to asso- 
ciate a data field buffer with’a specific SOL, statement. 


pos (binary integer) specifies the position of a field or expression in the 
select-list of a SQL query. Fields and expressions in a select-list 
are separated by commas. Each field or expression is then refer- 
enced positionally as if the fields were numbered left to right 
consecutively, beginning with 1. If the user specifies a position 
number greater than the number of fields in the select-list, 
ODPINN returns an end-of-fetch indicator in the return code field 
of the cursor data area. ODFINN uses the position number to 
release buffers to fields in the select-list. 


buffer (address) specifies the address of the data field buffer within the user 
program. 


bufl (binary integer) specifies the length of the buffer being defined. 





nI 


ftype (binary integer) specifies datatype to which the field is to be converted 
before it is moved to the user buffer. A list of external datatypes 
and type codes is contained in the chapter on datatypes. 


rcode (address) specifies the address of a short binary integer defined in the 
user program which will receive a field return code after'a 


OFETCH operation. 

fdig (binary integer) specifies the number of fractional digits to the right of 
the decimal point to be returned for fields of ftype 7 (COBOL 
packed decimal). fdig is required for datatype 7 and is ignored for 
all others. 





ODFINN Example 





odfinn(curs[1],1,&empno,2,3, (short *)1,-1); 
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SSeS. YyrYPYPe 
THE OBIND AND OBINDN CALLS 








CALL OBIND (cursor, sqlvar,[sqlv1], progvar, [progv1], ftype) 
CALL OBINDN (cursor, sqlvarnum, progvar,[progv1], ftype) 
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The OBIND and OBINDN calls are used to dynamically modify a SQL 
statement after it has been passed to ORACLE in a OSQL call. The 
statement may then be executed, modified again, and re-executed until 
completed. 


The OBIND and OBINDN calls have been replaced by the newer calls 
OBNDRV and OBNDRN. 


The OBIND and OBINDN calls specify that a program value is to be as- 
signed to a SQL substitution variable within a SQL statement. The calls 
differ only in the way they reference SQL substitution variables. OBINDN 
references SQL substitution variables numerically. OBIND references SQL 
substitution variables symbolically by name. The name of the variable to 
be bound must not be an ORACLE reserved word. 


At the time of the OBIND or OBINDN, ORACLE converts the program 
variable from external to internal format, then moves the data value into 
the SQL statement. OBIND and OBINDN are used after the OSQL call 
and prior to the OEXEC call. If the same substitution variable name oc- 
curs more than once, a single call to OBIND or OBINDN will bind them 
all. The number of variables bound is returned in the parse error offset field 
of the cursor data area. 


The completion status of the bind is indicated in the return code field of the 
cursor data area. Error return codes are listed in the ORACLE Error Mes- 
sages and Code Manual. If a character to numeric conversion error 
(ORACLE error + 5) occurs, binding will stop and the Return Code field 
will contain + 5, If an ORACLE error which has a negative value (such 
as 625, non-supported conversion) occurs, binding will stop and the parse 
error offset will indicate the variable name occurrence number where the 
error occurred. If the substitution name does not exist, the ORACLE error 
605 will be returned. 


cursor (address) specifies the address of a 64-byte data area within the user 
program. OBIND and OBINDN use the cursor name to refer- 
ence a specific SQL statement. 


sqlvar (address) specifies the address of a character string containing the 
name of a substitution variable within the SQL statement. The 
variable name is preceded by a colon (:) in the SQL statement, 
ic. WHERE EMPNO = :EMPLOYEL. OBIND and OBINDN 











move the program variable value into the SQL substitution vari- 
able EMPLOYEE. 


sqlvl (binary integer) specifies the length of the character string specified for 
sqivar, For example, -EMPLOYBE has a length of 9. If the 
substitution variable was specified as a null terminated character 
string, this parameter may be omitted. 


sqivarnum (binary integer) specifies the number of a SQL substitution var- 
iable within the SOL statement referenced by the cursor. For 
example, if sqlvarnum contains the value 2, it references a SQL 
substitution variable defined as :2. 


progvar (address) specifies the address of a variable defined within the user 
program. The value within the program variable is substituted 
into the SQL statement at the time of the bind. 


progvl (binary integer) specifies the length of the program variable. A 
length of 0 indicates a null value is to be bound to the progvar 
parameter. 


ftype (binary integer) specifies the datatype of the program variable as it is 
defined within the user program. ORACLE converts the program 
variable from external to internal format before it is bound to the 
SQL statement. A list of external datatypes and type codes is 
contained in the chapter on datatypes. 








| OBIND and OBINDN Example 





obind(curs,":ENAME",1,strings,-1,1); 
obindn(curs2,1,&deptno, 2,3); 
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CHAPTER 11. DATATYPES 








This chapter discusses the datatypes used by the OCI and the ORACLE 
RDBMS, and the conversions which can be performed. 


ORACLE performs data conversions for most datatypes provided by the 
supported languages. On retrieval (SELECT) operations, ORACLE con- 
verts from the internal format of the data as stored in the database to an 
external format as defined by the user program. On storage (INSERT and 
UPDATE) operations, ORACLE converts from external to internal 
datatypes. 


The user specifies the external datatype for SELECT operations with the 
ODEFIN call. The user specifies external datatypes for INSERT and 
UPDATE operations with the OBNDRV and OBNDRN calls. 


Internally, ORACLE stores characters in ASCH or EBCDIC strings and 
numbers in a variable length scaled integer format. ORACLE stores 
DATEs internally in seven bytes as YY YY MMDDHHMMSS. 


If the user does not want ORACLE to do any conversion on numeric data, 
the data may be defined as a character string for both the internal and ex- 
ternal datatype. 


DATATYPE DESCRIPTIONS 


Figure 17 on page 203 lists the external datatypes supported by ORACLE. 

A description of the ORACLE external datatypes follows: 

01 The varying length character string format is a string of 
ASCU/EBCDI characters whose length is determined by a length 


field, Trailing blank characters are discarded on input. ORACLE 
pads the string with trailing blanks on output. 
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If the length specification is missing on input, the string length is 
determined by scanning the string until a null character (a zero 
byte) is encountered, 240 characters will be scanned for a null 
character. If a null is not found, a string length of 240 will be 
used, 








Figure 17. 





























fp teen ne ee ete ee ee me 
DATATYPE | CODE FORTRAN | COBOL | c 

ESE EENET eo R e E ene 
Varying length 01 LOGICAL*1 | PIC X...X | CHAR 
Character string 
ORACLE internal 02 N/A N/A N/A 
numeric 
8-bit fixed point | 03 LOGICAL*1 | N/A | CHAR 
16-bit fixed point| 03 INTEGER*2 |PIC S9(4) COMP| SHORT 
32-bit Fixed point] 03 INTEGER*4 |PIC S9(9)COMP | LONG 

EA EEE E alte MO ete pha cease ca ccawuaman on ERE 
32-bit floating 04 REAL*4 N/A FLOAT 
point 

i cen naawa meee oe ee ist ee ee eee be ee eee eases ete 
64-bit floating 04 REAL *8 N/A DOUBLE 
point 

dunn anwar ewa gece eee lieu ee Ske ke cose eee 
Null terminated 05 LOGICAL*1 PIC X,..X CHAR 
string 

ES A E S E EANA EAE EE OAN E EE E EE 

| Raw data | 06 | LOGICAL*1 PIC X...X | CHAR 

ESEE Sieh Se Reo ee ie Gen ee E E 
COBOL packed 07 N/A PIC S9V9 N/A 
decimal COMP3 

ee i em e e m e e a m ea n + 

| LONG datatype | 08 | N/A | N/A | N/A | 

Pe a et ee enen e e me + 

| Unknown datatype | 10 | N/A N/A | N/A | 

ee m e e e m e e a e m oe m m m e I E I I E E E m e E e D a e e A t e e H e 1 = ae e me e e ee e + 

| ROWID | 11 | N/A N/A | N/A | 

Se ett ey + 

| ORACLE Internal DATE 12 | N/A N/A | N/A 

occ nr ee +------- pm meee e e e ea m e +- taenn + 

| Internal Julian | 14 | N/A N/A | N/A 

cp me ne m e e ee e e a me e ma e a ma m a m m m m e m e e e a + 


External Datatypes Supported by ORACLE 
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If a length is specified on input, no scan for null termination is 
performed. The length is required on output. An all blank field 
or one whose length is specified as zero on input is treated as a 
NULL by ORACLE. A zero length output length specification 
is invalid. When the ORACLE internal datatype is NUMBER, 
input character strings are converted to internal numeric format 
until an invalid numeric character is encountered, e.g., 
1234.45bed’ is converted to 1234.45, and the ‘bed’ is ignored with 
an ORACLE conversion error + 5 returned. Output to an ASCII 
character buffer from an internal numeric datatype can be made. 
Input from a character string which contains the ASCII character 
representation of the internal number is also legal. The field width 
determines the precision. The number will be converted to sci- 
entific notation if required by the field size., e.g., if the number is 
123456789 and the field width is 6, the output string will be 
1.2608". 








The general format of an ORACLE number follows: 








le elated fmf en af et ert re a crf nn en 
s 
i 
g 

Length nj} exponent digit digit 

b 
i 
t 

terreeememe m faba ee tremenen Spee ee += 





implied radix point 


Length is the length of number and is equal to the number of 
digits plus one. In some interfaces the length may be excluded and 
passed as a separate parameter. The length has a minimum of one 
and a maximum of the maximum size of an ORACLE number, 
The maximum size of an ORACLE number is a currently 22 
bytes. 


The sign bit is the high order bit of the exponent byte, If the sign 
bit is set the number is positive and if the sign bit is clear the 
number is negative. 


The exponent is the low order 7 bits of the exponent byte. The 
exponent ranges from 0 to 127 and is in excess 64 notation. The 
result of 64 subtracted from the exponent tells how many bytes 
to shift the number. If the result is negative, the number is to be 
shifted to the right of the implied radix point and if the result is 
positive the number is to be shifted to the left. 


Bach digit is a binary number from 0 to 99 and represents a base 
100 digit. Bach digit has 1 added to it to prevent binary 0 from 
occurring as a number. (Binary 0 would cause problems if the 
field were indexed.) Thus, the internal representation shows each 
digit as a binary number from 1 to 100. The first digit is always 
nonzero because all numbers are normalized. Negative numbers 
are transformed positive numbers. The transformation is done as 
follows: the negative exponent byte including the sign bit is the 
one’s complement of the positive exponent byte, Each negative 
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digit is the 100’s complement of its corresponding positive digit 
plus one. This means that a positive digit is subtracted from 100 
to get the corresponding negative digit. If a negative number does 
not have the maximum number of digits then a byte containing 
102 is appended to the number. This transformation of positive 
numbers to negative numbers guarantees that all ORACLE 
numbers will collate correctly. 


Zero is a one byte number containing 128. This is the exponent 
byte with the sign bit set and the smallest possible exponent (64). 
This guarantees that zero will collate below all positive numbers 

and above all negative numbers. 


Positive infinity is represented by two bytes (255,101). and nega- 
tive infinity is three bytes (1,1,102). These representations were 
chosen so the two infinities collate correctly. 


03 The integer number format is used to process numbers 
which have no fractional parts. The integer number 
is a signed binary number of one, two, or four bytes. 
The significance order is determined by the host lan- 
guage. The length specification is required for input 
and output. If the number being output from 
ORACLE is not integral, the fractional part is dis- 
carded. Integer numbers may be used only with 
internal numeric columns. 


04 The floating point number format is used to process 
numbers which have fractional parts, or which exceed 
the capacity of integer number format. The number 
is represented using the computer’s floating point for- 
mat with a length of either 4 or 8 bytes (REAL*4 or 
float, REAL*8 or double). The length specification 
is required for input and output. Since the internal- 
numeric format is decimal based, some precision may 
be lost during the conversion from the computer's bi- 
nary floating point format to and from ORACLE’s 
decimal format. 


05 The null terminated string format is exactly like the 
varying length character string format, except that the 
string is always terminated by one byte of zero (the 
NULL character), On input, the string length is used 
to limit the scan for the null terminator. If the null is 
not found, then the specified length will be used as the 
string length. If the length is not specified, an implied 
maximum string length of 240 is used. On output, the 
null is placed after the last character returned. If the 
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06 


07 


10 


string exceeds the field length specified, the string is 
truncated and the last character position of the buffer 
contains the null. Trailing blanks are discarded on 
input. A zero length string (null in the first position 
or an all blank ficld) is treated as NULL by 
ORACLE. 


The raw data format is used for binary data. The 
contents of the buffer are not interpreted in any way 
by ORACLE for either input or output. The length 
is required for input and output. On output, only the 
number of characters stored in the database are re- 
turned; the remainder of the output buffer is not 
modified. The number of characters actually returned 
may be determined using the ODSC call. 


The COBOL packed decimal datatype is used to re- 
turn nonintegral numbers from ORACLE to a 
COBOL datatype which is suitable for calculation. 
The COBOL data area must be a signed COMP3 
(packed) field with an implied decimal point. The 
number of digits to the right of the decimal point is 
specified with the ODEFIN call. For more informa- 
tion about defining conversion format strings see the 
description of ODEFIN. The value returned may be 
used as is for COBOL calculations or may be moved 
to a computational field prior to calculations. The 
number will never be converted to scientific notation. 
If the number to be returned loses significant digits 
during the conversion, ORACLE fills the buffer with 
“*” characters. 


The ORACLE LONG datatype is used to store data 
strings exceeding 240 bytes. It is only used for storage 
and retrieval of long strings and cannot be used in 
functions, expressions or WHERE clauses. It is gen- 
erally returned into a character string. 


When ODSC is used to query the datatype of an item 
in a select-list, there are certain expressions that con- 
tain substitution variables that cannot be evaluated 
until a value is bound to the variable. Ifa DATE item 
is subtracted by a substitution variable, the result is a 
number of Julian days (type 14) if the variable is an- 
other DATE, but is a DATE datatype (type 12) if the 
variable is a number, The actual type of the field can 
only be determined after the variable is bound. 
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ROWID is an internal ORACLE pointer to the 
physical address of a row in the database. It is gener- 
ally only used in the SELECT FOR UPDATE state- 
ment. See the ORACLE Database Administrator's 
Guide for more information on the use of ROWID. 


The ORACLE internal DATE datatype stores a date 
in a seven byte field containing in bytes from left to 
right: year (two bytes), month, day, hours, minutes, 
and seconds. Dates should generally be returned from 
ORACLE into an ‘01’ varying length character string 
by using the TO_CHAR function in the select-list of 
the SQL statement. 


An internal Julian datatype is the result of an ex- 
pression that subtracts one DATE datatype from an- 
other DATE datatype. It is the number of days 
between the two dates. 














DATA CONVERSIONS 





Figure 18 specifies the data conversions supported by ORACLE. 

















cpt ne ee ete te m e + 
SYSTEM FORMAT | TO ORACLE |FROM ORACLE 
ies ame NE DA cee ules cea ae Ae NONE 
USER FORMAT CHAR [NUMBER] CHAR [NUMBER 
belated oa late chomp en 
JASC1I/EBCDI YES | YES | YES | YES 
memamen mm e m opr a et ferme ae ep ef te 
J INTERNAL NUMERIC | YES | YES | YES | YES 
Ab ssh i sation i bem econ E ae aba teen 
8 BIT FIXED PT YES | - | YES 
st ot it m m e e = cen a aaa 
16 BIT FIXED PT. | YES | ~- | YES 
te te e ee en aaa 
32 BIT FIXED PT | YES | - | YES 
Pe tn tne me con ee i tate 
32 BIT FLOATING YES | - | YES 
rene m oft me tafe ee tn eof tr a aaa 
64 BIT FLOATING | | YES | - | YES 
cfict te ee me tt ee ee re fame fame ean 
NULL TERM. STR. | YES | YES | YES | YES 
a ee tt er een teen en roy 
[Ra DATA | YES | YES | YES | YES | 
Apii Ant MOROL ere te aan ee: pee ye H 
[osor PACKED | NO | NO | NO | YES *| 
SBC eta eh te Mer ROR een Se - 


Figure 18. Data Conversion Table 


NOTE: The COBOL ‘number’ datatype must have a picture of the fol- 
lowing form: 


PICTURE S9(N)V9(N) USAGE COMP3. 
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APPENDIX A. PRO*C ERROR MESSAGES 








Pro*C returns error or diagnostic messages during precompilation and also 
when running the precompiled program. 


There are four classes of Pro*C error messages, which are returned in the 
format: 


OCR error text 


The classes of errors are, in order of increasing severity: 


w These messages are Warnings, which will probably ignore the 
SQL statement in error and create a compilable output file. 


S These messages are more Severe than W messages, but still create 
output files. However, it is unlikely the program will run without 
correcting the error. 


F These messages indicate Fatal errors, resulting in no output. 
U These messages indicate Unrecoverable errors, also resulting in no 
output, 


Following are error messages which may appear during precompilation. 


Appendix A. Pro*C Error Messages / 211 

















1 Unable to open file %s 

2 Invalid syntax at column %u in line %u of file %s 

3 Invalid cursor name at column %u in line %u of file %s 

4 Invalid statement name at column %u in line %u of file %s 

5 Invalid descriptor name at column %u in line %u of file %s 

6 Invalid include file name at column %u in line %u of file %s 
7 Invalid WHENEVER condition at column %u in line %u of file %s 
8 Invalid WHENEVER action at column %u in line %u of file %s 

9 Invalid host variable at column %u in line %u of file %s 

10 Statement out of place at line %u in file %s 

11 Already in a declare section at line %u in file Zs 

12 Not in a declare section at line %u in file %s 

13 Unable to open include file \"%s\" at line %u in file %s 

14 Undeclared cursor name \"%s\" at line %u in file %s 

15 Undefined statement name \"%s\" at line %u in file %s 

16 Unable to open a cursor at line %u in file %s 

17 Unable to parse statement at line %u in file %s 

18 Expected \"%s\", but found \"%s\" at line %u in file %s 

19 Unable to obtain bind variables at line %u in file %s 

20 Unable to obtain define variables at line %u in file %s 

21 ORACLE Error: %s 

22 Out of space ~ unable to allocate %u bytes 

23 Unable to log off from ORACLE 

24 Indicator variable \"%s\" has wrong type or length at line %u in file %s 
25 Undeclared indicator variable \"%s\" at line %u in file %s 

26 Undeclared host variable \"%s\" at line %u in file %s 

27 Redeclared cursor \"%s\" at line %u in file %s 

28 Redeclared statement name \"%s\" at line %u in file %s 

29 Ambiguous option \"%s\" 

30 Invalid label range specified i 
31 Invalid operand \"%s\" for option \"%s\" 
32 Invalid option \"%s\" 

33 Missing operand for option \"%s\" 

34 Unable to create access module 

35 No host language specified 

36 No input file name specified 

37 Unable to log on to ORACLE with \"%s\" 

38 Unable to open a cursor 
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Unable to open input file \"%s\" 
Unable to open listing file \"%s\" 
Unable to open output file \"%s\" 


Out of space 
Array bound mismatch in INTO/USING. Minimum is: %s(%u:%u) 
FOR clause inappropriate at line %u in file %s. Ignored. 


PCO ERROR MESSAGES. 





1000 
1001 
1002 
1003 
1004 
1005 
1006 
1007 


Invalid character \"%c\" in indicator area at line %u in file %s 
Non-blank character \"%c\"" in area A at line %u in file %s 
Invalid continuation of literal at line %u in file %s 

Literal open at end-of-file 

Pseudo-text open at end~of-file 

In an EXEC statement at end-of-file 

PROCEDURE DIVISION not found 

Missing literal delimiter at line %u in file %s 


PCI ERROR MESSAGES 


1100 
1101 
1102 
1103 





Invalid label at line %u in file %s 

Too many descriptors needed in one program unit line %u in file %s 
Unable to generate descriptor in program unit ending line %u in file %s 
Out of label range at line %u in file %S 


PC2 ERROR MESSAGES 


1200 
1201 


Too many descriptors needed in one program unit line %u in file %s 
Unable to generate descriptor in program unit ending line %u in file %s 
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RUNTIME ERRORS 





2100 PCC: Out of Memory (i.e., couldn't al locate). 
Occurs when a malloc() fails in the precompiler runtime library. This can occur when Pro*C is 


attempting to allocate/expand the cursor cache. The program is too large to run; there is no 
workaround. 


2101 PCC: Inconsistent cursor cache (uce/cuc mi smatch) 
This is an internal error, meaning that either the cursor cache or a unit cursor entry has been been 
destroyed. Pro*C cursors are referenced “unit relative’. When you PCC a program, Pro*C gen- 
erates a Unit Cursor Entry (uce) array called sq/cun which contains an ordinal into the cursor cache 


(0 means the PCC (unit) cursor is not open). When a Pro*C (unit) cursor is opened, it is assigned 
a cuc. 


2102 PCC: Inconsistent cursor cache (no cuc entry for this uce). 
This is an internal error, which can occur if the uce contains a cuc ordinal, but when the precom- 


piler looks there, it finds no cuc entry. This "impossible condition” occurs only if the user’s pro- 
gram exceeds available memory. 


2103 PCC: Inconsistent cursor cache (out-of-range cuc ref). 


An internal error which can occur if the uce contains an ordinal in the cuc that is cither too big 
or less than zero. Indicates a problem with memory. 


2104 PCC: Inconsistent cursor cache (no cuc available). 
This error indicates there is no cursor cache. Indicates a problem with memory. 
2105 PCC: Inconsistent cursor cache (no cuc entry in cache). 
Under certain conditions, the runtime library 
performs a general “consistency check” of the cursor cache. If this check reveals that an entry in 
the cursor cache has mysteriously disappeared, this message results. Indicates a problem with 


memory. 


2106 PCC: Inconsistent cursor cache (OraCursor nr is bad). 


This message is issued if the runtime library discovers an invalid ORACLE cursor number while 
attempting an ORACLE operation. 
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APPENDIX B. GENERAL PROGRAMMING GUIDELINES 








Qualify all object names: You may own most of the objects (tables, views, 
indexes, etc.) that you access in your own programs. However, to access 

other user’s data, or to allow other users to run programs against your data, 
you must fully qualify the object's name. This means that you must prefix 
the name of the object with the name of its creator or owner. For example, 
to select from the table ADDRESSES owned by FONZIE, you would code 


something like: 
EXEC SQL SELECT NAME FROM FONZIE. ADDRESSES; 


References to tables owned by ORACLE usernames like OPS$SCOTT are 
valid, just as in SQL*Plus. 


You must have the appropriate access to the object to perform. the desired 
operation, and you must correctly reference the user’s ORACLE username 
and the object’s name. 


Following this practice will make your programs more portable and easier 
to maintain. 
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APPENDIX C. RESERVED WORDS 








Reserved words are keywords which ORACLE uses and which users can- 
not use for names of objects, such as tables, columns, or views, If you in- 
advertently use a reserved word, the usual error message is that wo rd is “not 
a valid name”. 
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ADD ALL 


ANY AS 

ASSIGN AT BETWEEN 
CLUSTER COLUMN 
CONTAIN CONTAINS 
CURRENT DATABASE DATAPAGES 
DECIMAL DEFINITION 
DISTINCT DOES 

ELSE ENDIF EVALUATE 
FLOAT FOR 
GRAPHIC GROUP 

IF IFDEF IMAGE 
INCREMENT INDEX 
INITIAL INSERT 
INTO IS 

LIST LOCK 
MINUS MODE 

NEW NOCOMPRESS 
NOWAINT NULL 

OLD ON 

OR ORACLE ORDER 
PRIOR PRIVILEGES 
REVOKE ROW 

ROWS RUN 

SHARE SIZE 
START STATEMENT SYNONYM 
TABLE THEN 

UID UNION 

USER USING 
VARCHAR VARGRAPHIC 
WITH STATEMENT 
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COMPRESS 
CRASH 
DATE 
DELETE 
DROP 
EXCLUSIVE 
FROM 
HAVING 
IMMEDIATE 
INDEXED 
INTEGER 
LEVEL 
LONG 
MODIFY 
NOSYSSORT 
NUMBER 
OPTIMIZE 
PARTITION 
PUBLIC 
ROWID 
SELECT 
SMALLINT 
SYSDATE 
TO 

UNIQUE 
VALIDATE 
VIEW 

UID 


AND 
ASSERT 
CHAR 
CONNECT 
CREATE 
DBA 

DESC 

EACH 

FILE 

GRANT 
IDENTIFIED 
IN 
INDEXPAGES 
INTERSEC 
LIKE 
MAXEXTENTS 
MOVE 


OPTION 
PCTFREE 
RESOURCE 
ROWNUM 
SET 
SPACE 
SYSSORT 
TRIGGER 
UPDATE 
VALUES 
WHERE 
USER 
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Appendix D presents a sample Pro*C program. 
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/* VOID sample 


*/ 


sample 


is a simple example program which adds new employee 
records to the personnel database. Checking 

is done to insure the integrity of the database. 

The employee numbers are automatically selected using 
the current maximum employee number + 10. 

The program queries the user for data as follows: 


Enter employee name: 
Enter employee job: 
Enter employee salary: 
Enter employee dept: 


The program terminates if control Z (end of file) 
or null string (<return> key) is entered when the 
employee name is requested, 


If the record is successfully inserted, the following 
is printed: 


ename added to department dname as employee # nnnnnn 
To build and run SAMPLE: 


C> pec iname=sample.pc include=\oracte\dbs 
prog=sample host=c userid=scott/tiger 

C> lec sample 

C> link \Ic\s\c.obj + sample.obj, sample, 

; sample. map, \\oracle\dbs\pecles. lib + 
\Ic\s\ic.1ib 

C> sample 


"Icc" is the compile step that takes the .C file from 
PCC and produces the .OBJ file needed by the linker. 
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#include <stdio.h> 

#include <ctype. h> 

EXEC SQL BEGIN DECLARE SECTION; 
VARCHAR uid[20]; 


/* username xf 
VARCHAR pwd[ 20]; 

/* password x] 
int empno; /* employee number Ky, 
VARCHAR ename[ 15]; 

/* employee name */ 
int deptno; /* department number */ 
VARCHAR dname[ 15]; 

/* department name */ 
VARCHAR job[15]; 

/* employee job */ 
int sal; /* employee salary */ 


EXEC SQL END DECLARE SECTION; 
EXEC SQL INCLUDE SQLCA; 


main() 


logon to ORACLE, and open the cursors. The program exits if 
any errors occur. 


strepy(uid.arr, "SCOTT" ); 
uid. len = strlen(uid.arr); 
strcpy(pwd. arr," TIGER"); 
pwd. len = strlen(pwd.arr); 


EXEC SQL WHENEVER SQLERROR GOTO errexit; 
EXEC SQL CONNECT :uid IDENTIFIED BY :pwd; 


EXEC SQL SELECT NVL(MAX(EMPNO),0) + 10 
INTO :empno 
FROM EMP; 
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read the user's input from STDIN. If the employee name is 

not entered, exit. 

Verify that the entered department number is valid and echo the 
department's name 


for( ; ; empnot+=10 ) 


int 1; 
/* Get employee name to be inserted, 


IMPORTANT NOTE: beware of coding as follows 


ename. len = asks("Enter employee name : ", ename.arr); 
if ( ename. len <= 0 ) 


etc.. 


In the above, asks() returns an int, but ename.len is an 
unsigned short (see SQLCA). Therefore, the "if" fails for 
<EOF> (which returns ~1) because, by definition, the 
unsigned short can't be negative. 


ay 
1 = asks("Enter employee name : ",ename.arr); 
if (1<=0) 
break; 
ename. len = 1; 
job. len = asks("Enter employee job : ",job.arr); 
askn("Enter employee salary: ",&sal); 
for (33 
if ( askn("Enter employee dept : ",&deptno) < 0 ) 
break; 


222 / Pro*C User's Guide 





e mae 





ST 


EXEC SQL WHENEVER NOT FOUND GOTO nodept; 
EXEC SQL SELECT DNAME 

INTO :dname 

FROM DEPT 

WHERE DEPTNO = :deptno; 
dname.arr[dname. len] = '\0'; 


EXEC SQL WHENEVER NOT FOUND STOP; 


/* Here if deptno was found in dbs. 
Insert new employee into dbs. */ 


EXEC SQL INSERT INTO EMP ( EMPNO, ENAME , JOB, SAL, DEPTNO) 
VALUES (:empno, :ename,:job,:sal,:deptno); 


printf("\n%s added to the %s department as employee number %d\n", 


ename.arr,dname.arr, empno); 
break; 
/* Here if deptno NOT found in dbs */ 
nodept: 
printf("\nNo such department\n"); 
continue; 


EXEC SQL COMMIT WORK RELEASE; 
printf ("\nEnd of the C/ORACLE example program. \n"); 
return(1); 


errexit: 
errrpt(); 
EXEC SQL ROLLBACK WORK RELEASE; 
return(0); 


/* me ma see 1an pen = m 1 m ey ee S ea E e M St a Pt pS et ht a e 


COUNT askn(text, variable) 


print the 'text' on STDOUT and read an integer variable from 
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SDTIN. 


text points to the null terminated string to be printed 

variable points to an integer variable 

askn returns a 1 if the variable was read successfully or a 
-1 if -eof- was encountered 


int askn(text, variable) 
char text[]; 
int *variable; 


oar s[20]; 


printf(text); 
if ( gets(s) == (char *)0 ) 
return( EOF); 
*variable = atoi(s); 
return(1); 
/* ee i ee ee i ee ee ek ee yk ak bd ee me ee Ot ere rm ph nr end mn 


COUNT asks(text, variable) 


print the 'text' on STDOUT and read up to 'len' characters into 
the buffer pointed to by variable from STDIN. 


text points to the null terminated string to be printed 
variable points to a buffer of at least 'len'+1 characters 


asks returns the number of character read into the string, or a 
-1 if -eof- was encountered 
int asks(text, variable) 


char text{],variablef J; 


{ 
printf(text); 
return( gets(variable) == (char *)O0 ? EOF : strlen(variable) ); 
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[8 mm re et te ae ee nnn se em ne 


VOID errrpt() 


errrpt prints the ORACLE error msg and number. 


errrpt() 


printf("\n%.70s (%d)", sqica.sqlerrm.sqlerrmc, -sqica.sqicode); 
return(0); 
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APPENDIX E. SAMPLE PRO*C PROGRAM WITH DYNAMIC SQL 








Appendix E presents a Pro*C program that uses dynamic SQL. 


Appendix E. Sample Pro*C Program with Dynamic SQL / 227 











n ee Se 
/* Copyright (c) 1984 by Oracle Corporation. */ 
#include <stdio.h> 


#include <ctype.h> 
#include "orastd.h" 


/* 
NAME 

MU : Mini-UFI. 
FUNCTION 


Simple UFI-like program to demonstrate dynamic SQL statements 
with the C precompiler. 


To build MU (on VMS): 
$ PCC INAME=MU. PC PROG=MU USERID=/ INCLUDE=SYS$ORACLE: 
: BSYSSORACLE: LOUTL MU MU,SYS$ORACLE:SQLLIB/LIB MU $ 
$ RUN MU 

To build MU (on VM/CMS): 
PCC INA=MU.CSQL 


CC MU 
LINKSQL MU 
MU 


#undef T 
#undef F 


#define CR 13 
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EXEC SQL BEGIN DECLARE SECTION; 


VARCHAR uid[30]; /* userid x] 
VARCHAR psswd[30] /* password xy: 
char *stmt; /* SQL stmt entered by user xy 


EXEC SQL END DECLARE SECTION; 


EXEC SQL INCLUDE SQLCA; 
EXEC SQL INCLUDE SQLDA; 


SQLDA  *bdp; /* -> Descriptor used for BIND vars xf 
SQLDA *sdp; /* -> Descriptor used for SELECT vars */ 
short *sdt = 0; /* -> arr of original DESCRIBE'd types */ 
int sdt]; /* nr of entries in sdt[] */ 
char *vars = 0; /* -> area used to hold Bind vars */ 
int bdSize = 5; /* Size of Bind variable descriptor */ 
int bvSize = 10; /* Max nr of chars in Bind Var name */ 
int sdSize = 5; /* Size of Select list descriptor ay 
int svSize = 80 /* Max nr chars in Select List colnames*/ 
int autoCom = FALSE; /* Perform automatic commits? */ 
int done = FALSE; /* Done executing statements? xy 
int reExec; /* Re-execute the same sql statement? */ 
extern char *malloc(); /* Allocate Memory “7 
extern char *sqlald(); /* Allocate Descriptor */ 
extern VOID  mufwrn(); /* Issue SQLWARNING Err Msg */ 
main(argc, argv) 
int argc; 
char  *argv[]; 
int i; 
int firstTime; /* Ast time statement executed ? x/ 
char answer[4]; /* String to hold answer to questions */ 


/* begin mu */ 


printf("MU V1.1 Interactive SQL Statement Executor\n\n"); 
printf("For help, type '/help;' at the prompt. \n"); 
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login(argc, argv); 


/* Allocate storage for the various descriptors and strings */ 
/* which will be used, and get the first command string */ 
stmt = malloc(256); 


if ( stmt == NULL ) 
{/* Problem alloc'ing memory?!? */ 
puts("MU FAIL: stmt = malloc(256)"); 
exit(EX_FTL); 
} 


bdp = sqlald(bdSize, bySize, 10); 
if ( bdp == NULL ) 
{/* Problem allocating memory?!? */ 
puts("MU FAIL: bdp = sqlald(bdSize, bvSize, 10)"); 
exit(EX_FTL); 
} 
sdp = sqlald(sdSize, svSize, 0); /* Allocate a new descriptor xy 
if ( sdp == NULL ) 
{/* Problem allocating memory? !? */ 
puts("MU FAIL: sdp = sqlald(sdSize, svSize, 0)"); 
exit(EX_FTL); 
} 
sdp->N = 0; /* init in case exit before DESCRIBE */ 
while (!getCom(stmt)); 


/* Begin Main Loop 7 
while (!done) 


EXEC SQL WHENEVER SQLERROR GOTO CHECKERR; 


/* Process any pseudo commands which the user enters x7 
while (stmt[0] == '/') 
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{ 

procCmd(&stmt[ 1]); 7* Process the pseudo command = */ 
if (done) break; /* Don't get another stmnt 
while (!getCom(stmt)); /* Get another command */ 


} 
if (done) break; /* Exit loop and cleanup x/ 
/* Parse the entered statement sf 

EXEC SQL PREPARE $ FROM : stmt; 


if ( sqlca.sqlwarn[0] == 'W' ) 
mufwrn(); /* Issue SQLWARNING Err Msg */ 


EXEC SQL DECLARE C CURSOR FOR S; 


/* Describe the bind variables into the descriptor bdp */ 
bdp->N = bdSize; 
descBind(); 


firstTime = TRUE; 
/* Make a note of the fact that this is the first time */ 
/* that this statement is being executed */ 


/* The following loop executes the statement parsed above */ 
7* over and over with different values for the bind vars. */ 


do 


{ 

if (bdp->F != 0) getBVVals(&vars); 
EXEC SQL OPEN C USING DESCRIPTOR bdp; 
if (firstTime) 


{ 

firstTime = FALSE; 

sdp->N = sdSize; 

descSel();_ /* Describe the select list variables */ 
if (sdp->F != 0) fillSelDesc(); 


} 
if (sdp->N != 0) doFetches(); 
else 
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{ 


printf("%u rows processed. \n", sqica.sqlerrd[2]); 


if (autoCom) commitWork(); 
} 


reExec = FALSE; 
for (5 3) 


/* UNTIL cmd == SQL statement !! /exit !! /run 


{ 
while (!getCom(stmt)); 


if (stmt[0] != '/') break; /* Got SQL statement 
procCmd(&stmt[1]); 

if (danei h reexee) break; /* Got /exit !! /run 
} 


} while(reExec); 


EXEC SQL CLOSE C; 

if (sdp->N ]= 0) freeSelVars(); 

if (vars ]= 0) {free(vars); vars = 0;} 
continue; 


CHECKERR: 

reptError(); 

sqica.sqlcode = 0; 

printf("\nCare to continue? "); 

fflush( stdout); 

gets(answer); 

if (toupper(answer[0]) != 'Y') 
{/* User does not wish to continue, 
rol1BkPr(); 
break; 
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Rollback, and exit. 


*f 


*/ 
*/ 


*/ 











/* Here if user wants to continue after error. x] 


while (!getCom( stmt) ); 


cleanUp(); 
EXEC SQL COMMIT WORK RELEASE; 


return; 


ERR_EXIT: 
reptError(); 
cleanUp(); 
EXEC SQL WHENEVER SQLERROR CONTINUE; 
EXEC SQL ROLLBACK WORK RELEASE; 
return; 


/* end mu */ 


} 





EXEC SQL WHENEVER SQLERROR STOP; 


EXEC SQL WHENEVER SQLWARNING CONTINUE; 
EXEC SQL WHENEVER NOT FOUND CONTINUE; 





/** mufwrn : Issue SQLWARNING Msg. 
VOID mufwrn() 

h begin mufwrn */ 

if( sqlca.sqlwarn[1] == 'W' ) 


puts("SQLWARNING: Column was truncated. "); 
else if ( sqlca.sqlwarn[2] == 'W' ) 


puts("SQLWARNING: Null values in aggregate (MAX, SUM) function."); 
) 


else if ( sqica.sqlwarn[3] == 'W' 
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TTN a 


puts("SQLWARNING: INTO var count not equal column count."); 
else if ( sqica.sqlwarn[4] == 'W! 

puts("SQLWARNING: Update or Delete without Where clause. "); 
else if ( sqlca.sqlwarn[5] == 'W' ) 

puts("SQLWARNING: ???,"); 


else if ( sqica.sqlwarn[6] == ‘Ww! 
puts("SQLWARNING: Rollback required."); 
else if ( sqica.sqlwarn[7] == 'W' ) 


puts("SQLWARNING: Change after query start on Select For Update."); 
/* end mufwrn */ 
cleanUp() anne 
{ 


if (sdp->N ]= 0) freeSelVars(); 
if (vars J= 0) {free(vars); vars = 0;} 


sqiclu(bdp); /* Free the bind variables descriptor  */ 
sqiclu(sdp); /* Free the select list descriptor */ 
~getCom(s) CMR ane E TAS Rete ate a 
char *s; 
{ 
int i, 1; 


char temp[ 256]; 


printf("MU: "); 

i fflush( stdout); 

| gets(s); 

| if ((1=strlen(s)) <=2) return( FALSE); 

if (s[1-1] == ';') {sE1-1] = '\0'; return(TRUE); } 
for (i = 2; ; i++) 


{ 

printf("%*u: ", 2, i); 
fflush(stdout); 
gets(temp); 
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strcat(s, " "); 

strcat(s, temp); 

if (s[(l=strlen(s)-1)] == 1,1) fsfi] = '\0'; return( TRUE); } 
} 


j 


porma 


tte e 


print(dp) o nn ha spite RN 


SQLDA *dp; 
{ 
int 1; 
int = *yp; 
short  *ip; 
/* begin print */ 
for (1 = 0; i < dp->N; i++) 


ts = dp-> If i]; 


if (*ip < 0) /* returned value is null */ 
printf("%-*s Oe dp->LẸi], n ih)» 
else 


printf("%-.*s u dp->L[i], dp->VLi]); 


putchar('\n'); 
/* end print */ 





ieee 
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EXEC SQL DESCRIBE BIND VARIABLES FOR S INTO bdp; 


if (bdp->F < 0) /* Descriptor not large enough av 
bdSize = ~(bdp->F); 
sqiclu(bdp); /* Get rid of current descriptor */ 
bdp = sqlald(bdSize, 10, 0); /* Allocate right size */ 


EXEC aaa DESCRIBE BIND VARTABLES FOR S INTO bdp; 


} 


login(argc, argv) 
int argc; 
char  *argv[]; 


/* begin login */ 







if ( arge == 2 ) 


{/* Caller provided usr/pwd. */ gneve ER 
strcpy(uid.arr,argv[1]); c Sab por gan WE, 

uid.len = strlen(arevi})s = SOLER 

psswd. len = 0; Mre co exit ond) 5 


EXEC SQL CONNECT : uid; a edly 
if ( sqica.sqlcode == 0 > TAT pa he Qld 
return; 


| puts("Problem logging in, please try again...\n"); 


for (3; 3 ) 
{ 


| printf("Username: "); 
fflush(stdout); 
gets(uid.arr); 
if (uid.arr[0] == '\O') return; 
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uid. len = strlen(uid.arr); 
printf("Password: "); 

fflush( stdout); 
gets(psswd.arr); 

psswd. len = strlen(psswd. arr); 


EXEC SQL CONNECT :uid IDENTIFIED BY :psswd; 
if ( sqlca.sqicode == 0 ) 


puts("Successfully connected. \n"); 
break; 


Gor logging in, please try again... \n"); 
; } 


EXEC SQL WHENEVER SQLERROR STOP; 


/* end login */ 
} 


getBVVals(vars) 

7* Get the user to supply values for each of the bind vars. 
/* Allocate a 10 byte string for each bind variable. 

char **vars;  /* A ptr to a ptr to storage for bind variables 








eamm, maons naman =e 


*/ 


int i; 
if (*vars == 0) 


{ 

žyars = malloc((bdp=>F) * 10); 

if ( *vars == NULE) 
{/* Problem allocating memory.?.]2..*/ 
puts("MU FAIL: *vars = malloc((bdp=pF) * 10)"); 
exit(EX_FTL); 
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} 
} 


/* Allocate a 10 byte string to hold the value that xf 
/* the user gives for each bind variable. 
printf("Please enter values for the bind variables: \n"); 
for (i = 0; i < bdp->F; i++) 

{ 

printf("%.*s: ", bdp->C[i], bdp->S[i]); 

bdp->V[i] = &((*vars)[1*10]); 

fflush( stdout); 

gets(bdp->V[i]); 

bdp->TLi] = 1; 

bdp~>L[i] = strlen(bdp->VLiJ); 
bdp->I[i] = 0; 
} 


és j everest merana ty a a at 


descSel() 
/* Describe the select list variables into sdp, expanding if */ 
/* necessary. Set desc. size to number of columns found. AY A 


EXEC SQL DESCRIBE SELECT LIST FOR $ INTO sdp 


if (sdp->F < 0) /* descriptor wasn't big enough */ 
sdSize = -(sdp->F); /* save correct size */ 
sqlclu( sdp); /* Free small descriptor */ 
sdp = sqlald(sdSize, 10, 0); /* Alloc., correct size */ 


EXEC SQL DESCRIBE SELECT LIST FOR S INTO sdp; 
sdp->N = sdp->F; 


ne sees “eter 
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/** doFetches() 


Print the column headers, do the fetches, and call print 


for each row found, Print count found. 
* 


doFetches( ) 

{ 
int cnt; 
char colname{ 100]; 
int colnamel; 


/* begin doFetches */ 

EXEC SQL WHENEVER NOT FOUND GOTO NOT_FND; — anaana 
/* Print column names wA 

putchar('\n'); 


for (cnt = 0; cnt < sdp->N; cnt++) 


{/* Print a column name: left~just for char; rt-just for number. 


colnamel = min(sdp->L[cnt], sdp->C[cnt]); 
colnamel = min(colnamel,sizeof(colname)~1); 
memcpy(colname, sdp->S[ cnt], colname1); 
colname[colname1] = '\0'; 


if ( sdt[cnt] == 2 ) 
{/* NUMBER: rt-justify. */ 
printf("%*s ", sdp->L[cnt],colname); 


else 
{/* Not NUMBER: left-justify. bk 
printf("%-*s ", sdp->L[cnt],colname); 
} 
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*/ 











/* Underline the column names */ 
putchar('\n'); 
for (cnt = 0; cnt < sdp->N; cnt++) 

int 7; 


for (i = 0; i < sdp->L[ent]; i++) 
putchar('-'); 


en '); 


putchar('\n'); 
/* Actually do the fetches and print the results xf 
“tor (cnt = 0; ; cnt++) 
{ 
EXEC SQL FETCH C USING DESCRIPTOR sdp; 
print(sdp); /* Print the results” of the fetch */ 
} 
NOT_FND: printf("\n%u row(s) selected\n", cnt); 
EXEC SQL WHENEVER NOT FOUND CONTINUE; 
/* end doFetches */ 
/** — £411SelDesc : Fill SELECT Descriptor. — TT “= — 


Allocate storage for each of the select list vars, and 


allocate storage for an indicator variable for each column 
A 


fi11Se1Desc() 
i 
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hoata 


int ï; 
unsigned char prec; 
char scale; 


/* begin fillSelDesc xf 


if ( tsdt ) 
{/* Haven't allocated sdt[] yet. */ 
sdt = (short *)mal loc( sizeof(short) * gdp->N); 


} 
else if ( sdt] < sdp->N ) 


{/* Need to reallocate saved type array. */ 
sdt = (short *Jrealloc(sdt, sizeof(short) ® sdp->N); 


} 
sdt] = sdp->N; 
for (i = 0; i < sdp->N; i++) 


7* Save original type; and clear possible NULL 
high-order bit. 


(sdp->TLi] & 0x8000); 
sdp~>TL i]; 


K 


sdp->T[i] 
sdt[i] 


if ( sdp->T[i] == 2 ) 
{/* Have NUMBER. Need to get precision and scale. */ 
prec = (unsigned char)(sdp->L[i} >> 8); 
scale = (char) sdp~>L[ iJ; 


u i 


if ( prec == 0 ) 
{/* No precision. User default. */ 
prec = 26; 


} 
sdp->L[i] = prec; 
if ( scale < 0 ) 


{/* Have scale. Need to add trailing zeros. */ 
sdp->LL i] += ~scale; 
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sdp->L[i] += 2; /* +2 for possible sign and decimal pt */ 
} 


else if ( sdp~>T[i] == 12 ) 
{/* Have DATE. Need to set default len for DD-MON-YY, */ 
sdp->L[i] = 9; 
} 


/* Coerce to CHAR, with max len = 240. */ 


sdp~>T[i] = 1; 
sdp->L[ i] = min(sdp->L[ i], 240); 


=2V[i] = malloc(sdp->L[i]); 
sdp->ILi])= malloc(sizeof(short)); 
/* end fillSelDesc */ 
} 


freeSelVars() 
/* Free the storage allocated to hold fetched values */ 


{ 
int i; 
for (i = 0; i < sdp->N; i++) 


free(sdp->Vf il): 
ree(sdp->I[ i]); 


sdp->N = 0; /* set to "have free()'d fetched-ya] storage" */ 
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/* Pseudo Command Procedures, Pseudo Command Processor, and xf! 
/* support routines for these. x 


/* Pseudo Command Procedures */ 


setReExecPr() f{reExec = TRUE; } 


resetAutoPr( 


autoCom = FALSE; printf("No longer in AutoCommit mode\n"); } 


feetDonePr() {done = TRUE; z> 


rol TBRP r~~- 


roliBackWork(); printf("Work Rolled Back\n"); } 


{ 
a TRUE; printf("Now in AutoCommit mode\n"); } 


f 
commitPr() {commitWork(); printf("Work Committed\n"); } 
helpPr() 
{ 


printf("\nMU V1.1 Help\n"); 
printf("To execute a SQL statement, simply type the statement\n" ); 
printf("when given the prompt. The statement may be entered\n"); 


printf("on several lines and must be terminated by a '; > In\n"); 
printf("fact, all commands must be terminated by a ';'. There\n"); 
printf("are several pseudo commands which begin with a '/'.\n"); 
printf("\nThe pseudo commands are:\n"); 


printf(" /cLommit] Commit Work\n"); 
printf(" /ro[11back] RollBack Work\n"); 
printf(" /ru[n] Reexecute the last SQL statement\n"); 
printf(" /e[xit] Exit this program\n"); 
printf(" /aLuto] _ Enter AutoCommit Mode\n"); 
printf(" /m[anua]l] Exit AutoCommit Mode\n"); 
printf(" /hLelp] Get this information\n"); 
printf("For more detailed information, read the code. \n"); 
} 
/* Pseudo Command Table and Command Processor */ 
struct comTabEntry { 
char *cmd; /* Unique prefix of pseudo command */ 
int (*proc)(); /* procedure to call */ 
} comTab[] = 
{"c" commitPr, 


, 
"po", rollBkPr, 

upy", setReExecPr, 
Ye" setDonePr, —> 2 
Na") satAutoPr, 
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"m", — resetAutoPr, 
"h", helpPr, 
ms 0 : 


procCmd(s) 
char *s; 
Í 
int i; 
int (*proc)(); 





{proc = comTab[i]. proc; (*proc)(); return; } 


/* Support Procedures for the pseudo commands and pc processor */ 


isPrfx(prfx, s) 
char *prfx, *s; 
int i, l; 
if ((l=strlen(prfx)) == 0) return(FALSE); 
for (1 = 0; i <1; i++) 
{ 
if ( toupper(*prfx) J= toupper(*s) ) 
return( FALSE); 
prfxt+; 
StH; 


} 
return(TRUE); 


rollBackWork() 
EXEC SQL ROLLBACK WORK; 


commitWork() 
{ 
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| 


| 
| 


| 
| 
| 
| 
| 








nee 


} 


EXEC SQL COMMIT WORK; 


/* Misc. Support routines xy: 


reptError() 


} 


printf("%.70s\n", sqica. sqlerrm. sqlerrmc); 
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APPENDIX F. C EXAMPLE PROGRAM 








SS ee 


This appendix contains a complete C program which prompts users for 
input (information about employees) and adds new employee records to the 
database after performing some checking. 


This example was written using the VAX/VMS C compiler. The program 
is available in the following files on the distribution media: 


VAX/VMS DEMO$ 
: SAMPLE. 
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** sample is a simple example program which adds new employee 
= records to the personnel data base. Checking is 


XK done to insure the integrity of the data base. The 
xe employee numbers are automatically selected using 
fa the current maximum employee number as the start. 
cial If any employee number is a duplicate, it is 
al skipped. The program queries the user for data as 
ad follows: 

RX Enter employee name: 

ae Enter employee job: 

kia Enter employee salary: 

xk Enter employee dept: 

KK 

we The program terminates if <end of file> is entered 
AR when the employee name is requested. 

KK 

wee If a record is successfully inserted, the following 
Te is printed: 

KK 

ae ename added to department dname as employee # nnnnnn 
mK 

ae The new employee number is 10 more than the highest 
IK previous employee number 

ae 

nae VMS LINKING INSTRUCTIONS: 

XK 

Ke $ @com$:1cee sample sample [d] [m] 

ww 

wR Specify d for DEBUG and m for MAP 

xy 


248 / Pro*C User’s Guide 














#include <stdio.h> 
#include <ctype. h> 
* 


** DEFINE THE c VERSION OF THE CURSOR (FOR 32 BIT MACHINES) 


*/ 
struct csrdef 
{ 
short esrrc; /*return code */ 
short csrft; /* function type */ 
unsigned long csrrpc; /* rows processed count */ 
short csrpeo; /* parse error offset */ 
unsigned char csrfc; /* function code */ 
unsigned char csrfil; /* filler */ 
unsigned short csrarc; /* reserved private */ 
unsigned char csrwrn; /* warning flags */ 
unsigned char csrflg; /* error flags */ 
/* xxx Operating system dependent *** 
KX 
/ 
unsigned int csrcn; /* cursor number */ 
struct { /* rowid structure */ 
struct f 
unsigned long  tidtrba; /* rba of first block of table r 
unsigned short tidpid; /* partition id of table */ 
unsigned char tidtbl; /* table id of table */ 
} ridtid; 
unsigned long  ridbrba; /* rba of datablock */ 
unsigned short ridsqn; /* sequence number of row in block */ 
} csrrid; 
unsigned int  csrose; /* os dependent error code */ 
unsigned char csrchk; /* check byte */ 
unsigned char crsfill[26]; /* private, reserved fill */ 
}; 
char *uid = "scott/tiger"; /* username/password */ 


char *insert = "INSERT INTO EMP(EMPNO, ENAME, JOB, SAL, DEPTNO) VALUES \ 


(:EMPNO, :ENAME, :JOB, :SAL, :DEPTNO)"; 
char *select = "SELECT DNAME FROM DEPT WHERE DEPTNO=: 1"; 
char *maxemp = "SELECT NVL(MAX(EMPNO), 0) + 10 FROM EMP" 
char *selemp = "SELECT ENAME, JOB FROM EMP"; /* find ename, 
job size */ 
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| NNN; 


main() 
int empno, sal, deptno; /* employee number, salary, dept number */ 
struct csrdef lda; /* 
lda area */ 
struct csrdef curs[2]; /* and two cursors */ 
char  hst [256]; /* Host definition */ 
char *ename, “job, *dept; /* employee name,job and de pt */ 


short enamel, job], depti; 
char *malloc(); 


#define LDA &lda 
#define CO (&curs[0]) 
#define C1 (&curs[1]) 
#define HST &hst 


#define DUPLICATE_VALUE -9 /* HLI interface return code */ 
#define INT 3 /* HLI integer type code */ 

#define CHRSTR 5 /* HLI null terminated string type */ 
/* 


** LOGON TO ORACLE, OPEN TWO CURSORS. NOTE: IN MOST SITUATIONS 
** THIS SIMPLE PROGRAM EXITS IF ANY ERRORS OCCUR. 
*/ 
if (orlon(LDA, HST, uid, -1, (char *)0, -1, -1)) 
{ 
errida(LDA, "orlon"); 
goto errexit; 
if (oopen(CO, LDA, (char *)0, -1, -1, (char *)0, -1)) 
errrpt(C0); 
goto errexit; 


if (oopen(C1, LDA, (char *)0, -1, -1, (char *)0, -1)) 


errrpt(C1); 
goto errexit 


/* 


** TURN OFF AUTO~COMMIT. NOTE: THE DEFAULT IF OFF, SO THIS COULD 
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** BE OMMITTED. 


* 


if (ocof(LDA)) 


errlda(LDA, "ocof"); 
goto errexit; 


J 


x 


%* RETRIEVE THE CURRENT MAXIMUM EMPLOYEE NUMBER 
K 
if (osq13(C0, maxemp, -1) 
|| odfinn(C0, 1, (unsigned char *)&empno, sizeof(empno), 

INT, -1, (short *)0, (char *)0, -1, ~1, {short *)0, 
(short *)0) 
oexec(C0) 
ofetch(C0)) 

{ 


errrpt(C0); 
goto errexit; 


/* 

%* DESCRIBE THE COLUMNS TO DETERMINE THE MAX LENGTH OF 
** THE EMPLOYEE NAME, JOB TITLE. 

K 


if (osq13(C0, selemp, -1) 
|| odsc(C0, 1, &enamel, (short *)0, (short *)0, (short *)0, 
(char *)0, (short *)0, (short *)0) 
|] odsc(CO, 2, &jobl, (short *)0, (short *)0, (short *)0, 
(char *)0, (short *)0, (short *)0) ) 


errrpt(C0); 
goto errexit,; 


} 


job = malloc(job1+1); /* don't forget room for null */ 
ename = malloc(enamel+1); 


/* PARSE THE INSERT AND SELECT STATEMENTS 


** DESCRIBE dname SO THAT WE CAN ALLOCATE SPACE 
** THEN DEFINE dept */ 
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/* 
we 
KK 


"Z 


/* 
kk 
Kk 
XR 
KK 


*/ 





if (osqi3(CO, insert, -1)) 
{ 


errrpt(C0); 
goto errexit; 


if (osq13(Cl, select, -1) 
|| odse(C1, 1, &deptl, (short *)0, (short *)0, (short *)0, 
(char *)0, (short *)0, (short *)0) 
|| odfinn(Cl, 1, dept = malloc(depti+1) , deptl+1, CHRST , 
(short *)0, (char *)0, -1, -1, (short *)0, (short * 0) ) 
{ 
errrpt(C1); 
goto errexit; 


} 


BIND SQL SUBSTITUTION VARIABLE VALUES USING BIND BY REFEREN 
STATEMENTS. 


if (  obndrv(C0, ":ENAME", -1, ename, (int)enamel+1, CHRSTR 
-1, (short *)0, (char *)0, ~1, -1) 
|| obndrv(co, ":JOB", -1, Job, (int)jobl+1, CHRSTR, 
-1, (short *)0, (char *)0, -1, -1) 
|| obndry(CO, ":SAL", -1, (unsigned char *)&sal, sizeof(sal), 
INT, ~1, (short *)0, (char *)0, -1, -1) 
|| obndrv(CO, ":DEPTNO",-1, (unsigned char *)&adeptno, sizeof(d eptno)| 
INT, -1, (short *)0, (char *)0, -1, -1 
| obndrv(CO, ":EMPNO", -1, (unsigned char *)&empno, sizeof(e mpno), 
INT, ~1, (short *)0, (char *)0, -1, -1) ) 
errrpt(C0); 
goto errexit 


} 


READ THE USER'S INPUT FROM stdin. IF THE EMPLOYEE NAME IS 

NOT ENTERED, THEN EXIT. VERIFY THAT THE ENTERED DEPARTMENT 
NUMBER IS VALID AND ECHO THE DEPARTMENT'S NAME WHEN DISPLAYING 
THE NEW ROW. 
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oo At 


/* 
eK 
* 


NE 


* 


/* 


KK 


*y 


/* 
KK 
* 


for( ; 
asks("Enter employee name : ", ename, enamel, 0) > 0; 
empno += 10) 
{ 
asks("Enter employee job : ", job, jobl, 0); 
aski("Enter employee salary: ", &sal, 0); 
while (aski("Enter employee dept : '", &deptno, 0) <= 0 
| obindn(C1, 1, (unsigned char *)&deptno, sizeof(deptno ), 
INT, -1, (char *)0, -1, -1) 
oexec(C1) 
ofetch(C1)) 
printf("\nNo such department %d\n", deptno); 


EXECUTE THE STATEMENTS. IF A DUPLICATE empno OCCURS, CALCULATE THE 
NEXT ONE AND EXECUTE AGAIN. 


while (oexec(CO) == DUPLICATE_VALUE) 
{ 


} 


empno += 10; 


IF ANY ERROR FROM OEXEC OCCURS AT THIS POINT, EXIT. 


if (CO->csrrc) 


} 


errrpt(C0); 
goto errexit; 


COMMIT THE CHANGE TO THE DATABASE. 


if (ocom(LDA)) 


} 


errida(LDA, “ocom"); 
goto errexit; 
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a amm 
/*  ** GIVE THE USER SOME FEEDBACK. */ 


printf("\n%s added to the %s department as employee number %d\n", 
ename, dept, empno); 
} 


/*  ** EITHER AN ERROR, OR USER ENTERED END-OF-FILE FOR EMPLOYEE NAME. 
** CLOSE THE CURSORS AND LOG OFF FROM ORACLE. */ 


errexit: 
oclose(C0); 
oclose(C1); 
ologof(LDA); 
printf ("\nEnd of the C/ORACLE example program. \n"); 
return(1); 


** errida AND errrpt PRINT THE ERROR CODE, OTHER INFORMATION. 


/*yoid*/ errrpt(cur) 
struct csrdef *cur; /* pointer to cursor */ 


char msg[80]; 
printf("ORACLE error: code is %d, op is %d\n", 
(int)cur->csrrc, (int)cur->csrfc); 
oermsg(cur->csrrc, msg); 
printf("%s\n" msg); 
} 
/* void */ errlda(lda,msg) 
struct csrdef *1da; /* pointer to the LDA */ 
char msg[]; /* user specified message */ 
{ 
char oertxt[80]; 
printf ("LDA error (%s): code is %d\n", (int)lda->csrrc); 
oermsg(Ida->csrrc, oertxt); 


printf("%s\n", oertxt); 
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APPENDIX G. PROGRAM CALL REFERENCE 





This appendix contains an alphabetical listing of all OCI calls, including the 
older calls used for compatibility with previous versions of the ORACLE 
RDBMS. 


For every call, the general syntax is shown with examples in C, COBOL, 
and FORTRAN. For explanation of the individual arguments, please refer 
to the section on the particular call. 








OBIND and OBINDN (New programs should use OBNDRN and OBNDRY) 





CALL OBIND (cursor, sqivar,[sq1v1], progvar, [progv1], ftype) 
CALL OBINDN (cursor, sqivarnum, progvar,[progv1], ftype) 





FORTRAN CALL OBIND( CURS, EMPNON, 1, EMPNO, 2,3) 
CALL OBINDN(CURS2, 1,DEPTNO, 2,3) 


COBOL CALL "OBINDN" USING CRC IN CURSOR~2, ONE, 
DEPTNO, DEPTNOL, ASC. 


CALL "OBIND" USING CRC IN CURSOR-1, EMPNO-N, EMPNO-N-L, 
EMPNO, FOUR, INTEGER. 


c obind(curs,":ENAME",1,strings,=1,1); 





obindn(curs2, 1,&deptno, 2,3); 
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=.= ti: eee ee 


E OBNDRV OBNDRN 








CALL OBNDRY (cursor, sqlvar, sqiv1, progvar, progv1, ftype[ , scale] 
[, indp][, fmt{, fmt?]], fmtt]]) 


CALL OBNDRN (cursor, sqlvarnum, progvar, prog], ftype[ , scale] 
[,indp][, fmt, fmt1]], fmtt]]) 





FORTRAN CALL OBNDRV(CURS( 1,2), JOBNAM, , STRNGS( ENAMEL+2) , JOBL, 1) 


COBOL CALL "OBNDRV" USING C-RC IN CURSOR~1, EMPNO-N, EMPNO-N~L, 
EMPNO, FOUR, PACKED, DEFLT, INDP, 
EMPNOF , SIX, PACKED. 
CALL "OBNDRV" USING C-RC IN CURSOR-1, ENAME-N, ENAME-N=L, 
ENAME , ENAME~L, ASC, DEFLT, INDP, EMPNOF, ZERO, ZERO. 


C obndrv (curs,":ENAME",~1, strings,-1,1,-1,(short *)-1, 
(char *)~1,0,0); 











OBREAK ] 





CALL OBREAK (1da) 








FORTRAN CALL OBREAK(HDA(1)) 
COBOL CALL "OBREAK" USING LDA-RC. 
c (obreak( 1da); 
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OCAN 
CALL OCAN (1da) 
FORTRAN CALL OCAN(LDA(1)) | 
coBoL CALL "OCAN" USING LDA-RC. 
c ocan(1da); 

OCLOSE | 
CALL OCLOSE (cursor) 
FORTRAN CALL OCLOSE(CURS) 
COBOL CALL "OCLOSE" USING C-RC IN CURSOR-1. 
c oclose(curs); 

OCMN (Not supported) 

CALL OCMN (Ida, comment, comment 1~) 
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OCOF 

CALL OCOF (1da) 

FORTRAN CALL OCOF(LDAREA) 

COBOL CALL "OCOF" USING LDA-RC. 

c if (ocof(curs[0])); 
OCOM 

CALL OCOM (lda) 

FORTRAN CALL OCOM(LDA) 

COBOL CALL "OCOM" USING LDA-RC. 


c (ocom( Ida); 





CALL OCON (Ida) 














FORTRAN CALL OCON( LDAREA) 
COBOL CALL "OCON" USING LDA-RC. 


c ocon( Ida); 
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ODEFIN 








CALL ODEFIN (cursor, pos, buffer, bufl, ftype [,scale] [,indp] 
[,fmt],fmt1}] [,fmtt ] ] [,ret?] [,rcode] ) 








FORTRAN CALL ODEFIN(CURS(1),1,EMPNO,2,3) 


COBOL CALL "ODEFIN" USING C-RC IN CURSOR-1,ONE,EMPNO, FOUR, 
PACKED, DEFLT, INDP, EMPNOF, SIX. 


c odefin(curs,1,&empno,2,3,-1,(short *)-1, (char *)-1, 
-1,-1,&rlen,&rcode); 


















ODFINN (New programs should use ODEFIN) 





CALL ODFINN (cursor, pos, buffer, buf I[, ftype][, rcode][, fdig]) 





FORTRAN CALL ODFINN(CURS, 1, EMPNO, 4,3, RCODE, 1) 


COBOL CALL "ODFINN" USING CRC IN CURSOR~2,ONE, 
DNAME , DNAME-L, ASC, RCODE, DEFLT. 


odfinn(curs[1],1,&empno,2,3,(short *)1,-1); 
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ae ODSC o] 


CALL ODSC (cursor, position [,dbsize] [,fsize] [,rcode] [,dbtype] 
{,cbuf, [cbufl]] [,dsize]) 











FORTRAN CALL ODSC(CURS(1),1,DEPTL) 
COBOL CALL "ODSC" USING C-RC IN CURSOR-2,ONE, DNAME-SIZE 
c odsc(curs,1,&deptl, (short *)01, (short *)01, 


(short *)01,(char *)-1,(short *)=1, (short *)-1) 














ODSRBN (New programs should use ODSC) 














CALL ODSRBN (cursor, position [,dbsize][ ,dbtype][, fsize]) 








FORTRAN CALL ODSRBN(CURS, 1, ENAMEL, ENAMES , ENAMFZ) 


COBOL CALL "ODSRBN" USING CRC IN CURSOR-1, ONE, ENAME-SIZE, 
ENAME_TYPE, ENAME_FSIZE. 


c odsrbn(curs[1],1,&enamel,(short *)1, (short *)-1) 
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OERMSG 





CALL OERMSG (rcode,msgbuf) 











FORTRAN CALL OERMSG(CURS(1,1), ERRMSG) 
COBOL CALL "OERMSG" USING ERR-RC,MSGBUF. 
c oermsg(cur-0-,msg); 

OEXEC 








CALL OEXEC (cursor) 





FORTRAN CALL OEXEC(CURS) 
COBOL CALL "OEXEC" USING C-RC IN CURSOR-1. 


c oexec(curs); 










OFETCH 


CALL OFETCH (cursor) 





FORTRAN CALL OFETCH(CURS ) 
COBOL. CALL "OFETCH" USING C-RC IN CURSOR~1. 
c ofetch(curs); 
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OLOGOF 





CALL OLOGOF (1da) 





FORTRAN CALL OLOGOF(LDA) 
COBOL CALL "OLOGOF" USING LDA-RC. 
c ologof(1da); 














OLOGON (New programs should use OLON) 





CALL OLOGON (Ida [,areacount]) 





FORTRAN CALL OLOGON( LDAREA) 
COBOL CALL "OLOGON" USING LDAREA, AREACOUNT. 
C ologon (Idarea,2); 





CALL OLON ( ida [,uid, uidlen] [,psw, pswl] [,0] ) 


FORTRAN CALL OLON(LDA(1),UIDPSW,,, ,0) 


COBOL CALL "OLON" USING LDA-RC,USER~ID,USER-ID-L, 
PSW, PSWLEN, ZERO. 


olon(Ida,uid,-1,(char *)-1,-1,0); 
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eee 








ONAME ] 





CALL ONAME (cursor, position, tbuf, tbufl, cbuf, cbufl) 











| 
FORTRAN CALL ONAME(CURS1, 2, TABLE, TABLEL, COL, COLL) 
COBOL CALL "ONAME" USING CURS4,SELPOS, 
TABLE, TABLEL, COL, COLL 
Ç oopt(curs, 2,4) 
ORES (Not supported) _| 





CALL ORES (cursor) 








ORLON 








CALL ORLON ( Ida, hda [,uid, uidlen] [,psw, pswl] [,audit_flag] ) 


FORTRAN CALL ORLON( LDA( 1), UIDPSW, ,,,0) 

COBOL CALL "ORLON" USING LDA-RC , USER- ID, USER- ID-L, 
PSW, PSWLEN, ZERO. 

c orlon(ida,uid,-1,(char *)-1,-1,0); 
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[ OROL 
+ 
CALL OROL (1da) 
— 
FORTRAN CALL OROL(LDA) 
COBOL CALL "OROL" USING LDA~RC. 
c orol(lda); 
OSQL (New programs should use OSQL3) q] 





CALL OSQL (cursor, sqlstatement [,sqllen]) 





FORTRAN CALL OSQL(CURS, SQLSTM, SQLSTL) 





COBOL CALL "OSQL" USING C-RC IN CURSOR=1, 
SQL-SELEMP , SQL-SELEMP-L 
c osqi(curs[1],"SELECT NVL(MAX(EMPNO) FROM EMP" ,-1); 
OSQL3 


CALL OSQL3 (cursor, sqistatement [,sqllen] ) 


FORTRAN CALL OSQL3(CURS(1), SQLSTM) 


COBOL CALL "OSQL3" USING CRC IN CURSOR~1, 
SQL~SELMAX , SQL~SELMA-L. 


c if (osq13(curs, "SELECT ENAME, JOB FROM EMP", -1) 








ee 
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DIZO aaee 


GLOSSARY 


active set: The set of rows which satisfy all the 
criteria of a query. The set of rows returned by a 
SELECT statement. See also “current row”. 


bind variable: Host variable which will contain a 
value to be sent to the database. 


closed state: The state of a cursor after it has been 
closed and is no longer associated with an active 
set. If a cursor is closed, the active set is unde- 
fined. 


current row: The latest row of the active set 
which has been fetched by a cursor. Each subse- 
quent FETCH moves the cursor through the rows 
of the active set. 


cursor; When used with no prefix, understood to 
mean a Pro*C cursor. A Pro*C cursor is required 
for every SQL operation, but may be acquired. 
automatically by Pro*C, or explicitly with the 
cursor statements. See also “OraCursor”. 


declarative statement: A type of Pro*C call which 
generates no code nor has any impact on the log- 
ical unit of work. For example, 


BEGIN DECLARE SECTION 
INCLUDE SQLCA 


Contrast with “executable statements”. 


descriptor: A structure used to pass information 
between a program and ORACLE. Such a struc- 
ture is used to pass input (bind variables, input 
host variables) to ORACLE, and a like structure 
is also used to pass output (INTO variables and 
output host variables) from ORACLE to the pro- 
gram. The visible structure of the descriptor is the 
SQLDA (SQL descriptor area). 


dynamic SQL statements: SQL statements which 
may change from one execution to the next. 
Typically this means that a user can enter any 
valid SQL statement at at terminal while running 





the Pro*C program, and the Pro*C program is 
responsible for interpreting, checking, and execut- 
ing the statement. 


executable statement: A statement which gener- 
ates C code and actual calls to the database. In- 
cludes SQL DML, DDL, and DCL statements. 
After every execution of an executable call, the 
SQLCA is updated. 


host variable: A variable declared in the host lan- 
guage (C) which is also referenced in SQL state- 
ments, as a means of passing data between the 
ORACLE database and the application program. 


indicator variable: A variable declared in the host 
language (C) which is used for field-specific infor- 
mation, such as NULL value returned or data 
truncation. Every indicator variable must corre- 
spond to a host variable, though every host vari- 
able need not have an indicator variable. 


input host variable: A host variable which is used 
as input to the application. Usually used in the 
WHERE clause of the SQL statement. For ex- 
ample, a variable by which an end user can enter 
the social security numbers for employees whose 
records will be updated, Also called using vari- 
ables or bind variables. 


open state: The state of a cursor after it has been 
opened and has therefore identified the rows of the 
active set. If a cursor is open it is positioned at the 
current row of the active set. 


OraCursor: A physical ORACLE cursor, one of 
which is obtained for every SQL operation. 


output host variable: A host variable which is 
used as output for the application. Usually used 
in the INTO clause of the SQL statement. For 
example, a variable where an application places 
the results of a query. Also called into variables 
or define variables. 


result code: A general term indicating that one of 
the elements of the SQLCA has been set. Same 
as “status code”. 
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SQLCA (SQL communications area): A structure 
used to pass information in the form of “return 
codes” about the execution of a program. For 
example, one element indicates when character 
data has been truncated, and another indicates 
when the number of items in the SELECT list is 
different than the number of items in the INTO 
clause, 


SQLDA (SQL descriptor area): The visible por- 
tion of a descriptor. One SQLDA is used for input 
or bind variables; another SQLDA is used for 
output or INTO variables, 


SQLCODE: One of the elements of the SQLCA 
which summarizes the results of executing a SQL 
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statement. A zero indicates successful execution; 
a positive code indicates success with an excep- 
tional condition, and a negative code indicates an 
error. 


statement name: The name given to the SQL 
statement when PREPARE precompiles the 
statement. This name is used by the EXECUTE 
statement, but it is nod declared as a host variable 
in the DECLARE section. 


status code: A general term indicating that one 
of the elements of the SQLCA has been set. Same 
as “result code”. 
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